User's Manual Rev. 1.2 May 19, 1999 A G R E E M E N T OSEK Operating System N O N - D I S C L O S U R E HC12 R E Q U I R E D OSEK Operating System Rev. 1.2 N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D User's Manual Motorola reserves the right to make changes without further notice to any products herein to improve reliability, function or design. Motorola does not assume any liability arising out of the application or use of any product or circuit described herein; neither does it convey any license under its patent rights nor the rights of others. Motorola products are not designed, intended, or authorized for use as components in systems intended for surgical implant into the body, or other applications intended to support or sustain life, or for any other application in which the failure of the Motorola product could create a situation where personal injury or death may occur. Should Buyer purchase or use Motorola products for any such unintended or unauthorized application, Buyer shall indemnify and hold Motorola and its officers, employees, subsidiaries, affiliates, and distributors harmless against all claims, costs, damages, and expenses, and reasonable attorney fees arising out of, directly or indirectly, any claim of personal injury or death associated with such unintended or unauthorized use, even if such claim alleges that Motorola was negligent regarding the design or manufacture of the part. Motorola and are registered trademarks of Motorola, Inc. Motorola, Inc. is an Equal Employment Opportunity/Affirmative Action Employer. Copyright (c) 1999 Motorola, Inc. All Rights Reserved User's Manual 2 MC68HC(7)05H12 -- Rev. 1.2 MOTOROLA The software described in this document is furnished under a license agreement. The software may be used or copied only in accordance with the terms of the agreement. Copyright (c) 1999 Motorola, Inc. All Rights Reserved No part of this publication may be reproduced or transmitted in any form or by any means - graphic, electronic, electrical, mechanical, chemical, including photocopying, recording in any medium, taping, by any computer or information storage retrieval systems, etc., without prior permissions in writing from Motorola Inc. Permission is granted to reproduce and transmit the Problem Report Form, the Customer Satisfaction Survey, and the Registration Form to Motorola. IMPORTANT NOTICE TO USERS While every effort has been made to ensure the accuracy of all information in this document, Motorola assumes no liability to any party for any loss or damage caused by errors or omissions or by statements of any kind in this document, its updates, supplements, or special editions, whether such errors are omissions or statements resulting from negligence, accident, or any other cause. Motorola further assumes no liability arising out of the application or use of any product or system described herein; nor any liability for incidental or consequential damages arising from the use of this document. Motorola disclaims all warranties regarding the information contained herein, whether expressed, implied or statutory, including implied warranties of merchantability or fitness for a particular purpose. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Legal Notices 3 R E Q U I R E D The information in this document has been carefully checked and is believed to be entirely reliable, however, no responsibility is assumed for inaccuracies. Furthermore, Motorola reserves the right to make changes to any products herein to improve reliability, function or design. Motorola does not assume liability arising out of the application or use of any product or circuit described herein; neither does it convey any license under its patent rights or the rights of others. A G R E E M E N T iii N O N - D I S C L O S U R E Legal Notices R E Q U I R E D Legal Notices TRADEMARKS Microsoft, MS-DOS and Windows are trademarks of Microsoft. N O N - D I S C L O S U R E A G R E E M E N T UNIX is a trademark of AT&T Bell Laboratories. User's Manual 4 OSEK Operating System -- Rev 1.2 Legal Notices MOTOROLA Table of Contents Section 1. Overview R E Q U I R E D User's Manual -- OSEK Operating System Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 2.2 Manual Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 2.3 Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 2.4 Definitions, Acronyms and Abbreviations . . . . . . . . . . . . . . . . . 27 2.5 Installation Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 2.5.1 Required Environment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 2.5.2 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 2.6 Technical Support Information . . . . . . . . . . . . . . . . . . . . . . . . . 29 Section 3. Operating System Architecture 3.1 Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 3.2 Processing Levels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 3.3 Conformance Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 3.4 OSEK OS Overall Architecture . . . . . . . . . . . . . . . . . . . . . . . . . 35 3.5 Application Program Interface . . . . . . . . . . . . . . . . . . . . . . . . . 37 Section 4. Task Management 4.1 Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 4.2 Task Concept . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 4.3 Task State Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 4.3.1 Extended Tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 4.3.2 Basic Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 4.4 Task Activation and Termination . . . . . . . . . . . . . . . . . . . . . . . 44 4.5 Task Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Table of Contents 5 N O N - D I S C L O S U R E 2.1 A G R E E M E N T Section 2. Notation R E Q U I R E D Table of Contents 4.6 Task Priorities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 A G R E E M E N T 4.7 Task Related Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 4.7.1 Task Configuration Table . . . . . . . . . . . . . . . . . . . . . . . . . . 49 4.7.2 Task Control Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 4.7.2.1 Persistent Node Assignment . . . . . . . . . . . . . . . . . . . . . . 52 4.7.3 Task Link Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 4.7.4 Task Stack. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 4.7.4.1 Stack Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 4.7.5 Allocation of Fixed Stack Linked with the Task Node . . . . . 56 4.7.5.1 Dynamic Stack Allocation from the Stack Pool . . . . . . . . 57 4.7.5.2 Persistent Stack Allocation from the Stack Pool . . . . . . . 57 4.7.5.3 Explicit Stack Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . 59 4.7.5.4 Stack Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 4.8 Programming Issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 4.8.1 Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 4.8.2 Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 4.8.3 Task Definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 4.8.4 Run-time Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 4.8.5 Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 4.8.6 Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 N O N - D I S C L O S U R E Section 5. Scheduler 5.1 Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 5.2 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 5.2.1 Simple Scheduler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 5.3 Scheduling Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 5.3.1 Non-preemptive Scheduling . . . . . . . . . . . . . . . . . . . . . . . . 67 5.3.2 Full-preemptive Scheduling. . . . . . . . . . . . . . . . . . . . . . . . . 68 5.3.3 Mixed-preemptive Scheduling . . . . . . . . . . . . . . . . . . . . . . . 69 5.4 Programming Issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 5.4.1 Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 5.4.2 Run-time Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 5.4.3 Scheduler Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Section 6. Interrupt Processing 6.1 Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 6.2 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 User's Manual 6 OSEK Operating System -- Rev 1.2 Table of Contents MOTOROLA 6.4 ISR Categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 6.4.1 ISR Category 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 6.4.2 ISR Category 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 6.4.3 ISR Category 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 6.5 Interrupt Flag Manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 6.6 Local Variables Considerations . . . . . . . . . . . . . . . . . . . . . . . . 78 6.7 Programming Issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 6.7.1 Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 6.7.2 Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 6.7.3 Run-time Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 6.7.4 Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 6.7.5 ISR Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 6.7.6 Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Section 7. Resource Management 7.1 Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 7.2 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 7.3 Access to Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 7.3.1 Priority Ceiling Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 7.3.2 Scheduler as a Resource . . . . . . . . . . . . . . . . . . . . . . . . . . 88 7.4 Programming Issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 7.4.1 Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 7.4.2 Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 7.4.3 Run-time Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 7.4.4 Resource Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 Section 8. Counters and Alarms 8.1 Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 8.2 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 8.3 Counters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 8.4 Alarms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 8.5 Programming Issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 8.5.1 Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 8.5.2 Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100 OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Table of Contents 7 A G R E E M E N T ISR Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 N O N - D I S C L O S U R E 6.3 R E Q U I R E D Table of Contents R E Q U I R E D Table of Contents 8.5.3 8.5.4 8.5.5 Counters and Alarm Generation . . . . . . . . . . . . . . . . . . . .101 Run-time Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102 Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103 Section 9. Events 9.1 Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105 9.2 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105 9.3 Events and Scheduling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .106 A G R E E M E N T 9.4 Programming Issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108 9.4.1 Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . .108 9.4.2 Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108 9.4.3 Events Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108 9.4.4 Run-time Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109 9.4.5 Additional Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109 N O N - D I S C L O S U R E Section 10. Communication 10.1 Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111 10.2 Message Concept. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111 10.3 Unqueued Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113 10.4 Queued Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .115 10.5 Programming Issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116 10.5.1 Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . .116 10.5.2 Identifiers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117 10.5.3 Message Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .118 10.5.4 Run-time Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119 10.5.5 Usage of Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119 Section 11. Error Handling and Special Routines 11.1 Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121 11.2 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121 11.3 Hook Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121 11.4 Error Handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .126 11.4.1 Error Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .126 11.4.2 Extended Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .127 User's Manual 8 OSEK Operating System -- Rev 1.2 Table of Contents MOTOROLA 11.5 Start-up Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .128 11.6 Application Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .130 11.7 System Shutdown. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .130 11.8 Programming Issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131 11.8.1 Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . .131 Section 12. System Configuration 12.1 Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .133 12.2 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .133 12.3 Application Configuration File . . . . . . . . . . . . . . . . . . . . . . . . .134 12.4 OIL Concept . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .134 12.4.1 OIL File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .134 12.4.2 Standard OIL Format. . . . . . . . . . . . . . . . . . . . . . . . . . . . .135 12.4.3 Extended OIL Format . . . . . . . . . . . . . . . . . . . . . . . . . . . .135 12.4.4 Implementation Definition . . . . . . . . . . . . . . . . . . . . . . . . .135 12.4.4.1 Implementation Definition Grammar . . . . . . . . . . . . . . .136 12.4.5 Application Definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . .138 12.4.5.1 Object Definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .138 12.4.5.2 Include Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139 12.4.5.3 Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139 12.4.5.4 File Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139 12.4.6 Configuration File Rules . . . . . . . . . . . . . . . . . . . . . . . . . .140 Section 13. System Objects Definition 13.1 Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .141 13.2 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .141 13.3 OS Definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .142 13.3.1 Global System Attributes. . . . . . . . . . . . . . . . . . . . . . . . . .142 13.3.2 Task Related Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . .147 13.3.3 Interrupt Related Properties . . . . . . . . . . . . . . . . . . . . . . .149 13.3.4 Resources and Events Related Attributes. . . . . . . . . . . . .151 13.3.5 Counters and Alarms Related Attributes . . . . . . . . . . . . . .152 13.3.6 Messages Related Attributes . . . . . . . . . . . . . . . . . . . . . .153 13.3.7 Hook Routines Related Attributes . . . . . . . . . . . . . . . . . . .154 13.3.8 OS Service Related Attributes. . . . . . . . . . . . . . . . . . . . . .155 OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Table of Contents 9 A G R E E M E N T Possible Error Reasons. . . . . . . . . . . . . . . . . . . . . . . . . . .128 N O N - D I S C L O S U R E 11.4.3 R E Q U I R E D Table of Contents R E Q U I R E D Table of Contents 13.4 Task Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .156 13.4.1 Object Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .156 13.4.2 Object References. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .158 13.5 Stack Definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .159 13.5.1 Object Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160 13.6 Resource Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160 13.6.1 Object Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .161 A G R E E M E N T 13.7 Event Definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .161 13.7.1 Object Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .161 13.8 Counter Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .161 13.8.1 Object Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .162 13.9 Alarm Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .163 13.9.1 Object References. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .163 13.10 Message Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .164 13.10.1 Object Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .164 13.10.2 Object References. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .166 13.11 ISR Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .167 13.11.1 Object Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .167 13.11.2 Object References. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .167 N O N - D I S C L O S U R E 13.12 Different Application Modes Definition . . . . . . . . . . . . . . . . . .168 Section 14. Building of Application 14.1 Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .171 14.2 Application Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .171 14.3 Action Sequence to Build an Application . . . . . . . . . . . . . . . .172 14.3.1 Application Configuration . . . . . . . . . . . . . . . . . . . . . . . . .173 14.3.2 Source Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .175 14.3.3 Compiling and Linking . . . . . . . . . . . . . . . . . . . . . . . . . . . .178 14.4 Sample Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .178 Section 15. HC12 Platform-Specific Features 15.1 Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .179 15.2 Compiler-Specific Features . . . . . . . . . . . . . . . . . . . . . . . . . .179 15.2.1 OSEK OS Environment Variables . . . . . . . . . . . . . . . . . . .179 User's Manual 10 OSEK Operating System -- Rev 1.2 Table of Contents MOTOROLA Interrupt Flag Manipulation Specific Features . . . . . . . . . . . .180 15.4 HC12 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .182 15.4.1 Base Page Memory Usage . . . . . . . . . . . . . . . . . . . . . . . .182 15.4.1.1 Mapping RAM and REGISTERS . . . . . . . . . . . . . . . . . .182 15.4.2 Interrupt Vector Table . . . . . . . . . . . . . . . . . . . . . . . . . . . .183 15.4.3 The Banked Memory Model Support. . . . . . . . . . . . . . . . .184 15.4.3.1 Banked Memory Model Overview . . . . . . . . . . . . . . . . .184 15.4.3.2 Configuration of the Application for Banked Memory. . .185 15.4.3.3 Cosmic Compiler Issue . . . . . . . . . . . . . . . . . . . . . . . . .186 15.4.4 Recommendations on System Properties . . . . . . . . . . . . .187 15.4.4.1 UseMainStack property . . . . . . . . . . . . . . . . . . . . . . . . .187 15.4.4.2 UseSameContext Property . . . . . . . . . . . . . . . . . . . . . .187 15.4.4.3 InterruptMaskControl Property . . . . . . . . . . . . . . . . . . . .187 15.4.4.4 CounterSize Property. . . . . . . . . . . . . . . . . . . . . . . . . . .188 15.4.4.5 Unused Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .188 15.4.5 System Timer Hardware . . . . . . . . . . . . . . . . . . . . . . . . . .188 15.4.6 Scheduler Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . .191 15.4.7 Alarms Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . .191 15.5 Task Stack Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .192 Section 16. Application Troubleshooting 16.1 Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .193 16.2 System Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .193 16.3 Using OS Extended Status for Debugging . . . . . . . . . . . . . . .193 16.4 Context Switch Routines. . . . . . . . . . . . . . . . . . . . . . . . . . . . .194 16.5 Stack Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .195 16.6 Known Problems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .195 Section 17. System Services 17.1 Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .197 17.2 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .197 17.3 Task Management Services . . . . . . . . . . . . . . . . . . . . . . . . . .199 17.3.1 Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .199 17.3.2 Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .199 17.3.3 Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .200 OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Table of Contents 11 A G R E E M E N T 15.3 Cosmic Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .180 N O N - D I S C L O S U R E 15.2.2 R E Q U I R E D Table of Contents R E Q U I R E D Table of Contents A G R E E M E N T 17.3.4 17.3.5 17.3.6 17.3.7 17.3.8 17.3.9 17.3.10 17.3.11 17.3.12 Task Declaration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .200 ActivateTask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .201 TerminateTask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .202 ChainTask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .203 Schedule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .204 GetTaskId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .205 GetTaskState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .206 GetTCBInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .207 Examples for Task Management Services . . . . . . . . . . . .208 17.4 ISR Management Services . . . . . . . . . . . . . . . . . . . . . . . . . . .210 17.4.1 Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .210 17.4.2 Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .211 17.4.3 Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .211 17.4.4 EnterISR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .211 17.4.5 LeaveISR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .213 17.4.6 EnableInterrupt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .214 17.4.7 DisableInterrupt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .216 17.4.8 GetInterruptDescriptor. . . . . . . . . . . . . . . . . . . . . . . . . . . .217 17.4.9 Examples for Interrupt Management Services . . . . . . . . .218 N O N - D I S C L O S U R E 17.5 Resource Management Services . . . . . . . . . . . . . . . . . . . . . .220 17.5.1 Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .220 17.5.2 Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .220 17.5.3 Resource Declaration . . . . . . . . . . . . . . . . . . . . . . . . . . . .221 17.5.4 GetResource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .221 17.5.5 ReleaseResource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .223 17.5.6 Examples of Using Resources . . . . . . . . . . . . . . . . . . . . .224 17.6 Counters and Alarms Management Services . . . . . . . . . . . . .225 17.6.1 Data Types and Identifiers . . . . . . . . . . . . . . . . . . . . . . . .225 17.6.2 Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .226 17.6.3 Counter and Alarm Declaration . . . . . . . . . . . . . . . . . . . . .227 17.6.3.1 Counter Declaration . . . . . . . . . . . . . . . . . . . . . . . . . . . .227 17.6.3.2 Alarm Declaration . . . . . . . . . . . . . . . . . . . . . . . . . . . . .228 17.6.4 InitCounter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .228 17.6.5 CounterTrigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .229 17.6.6 AdvanceCounter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .230 17.6.7 GetCounterValue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .231 17.6.8 GetCounterInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .232 17.6.9 SetRelAlarm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .233 User's Manual 12 OSEK Operating System -- Rev 1.2 Table of Contents MOTOROLA 17.7 Event Management Services . . . . . . . . . . . . . . . . . . . . . . . . .242 17.7.1 Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .242 17.7.2 Event Declaration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .242 17.7.3 SetEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .243 17.7.4 ClearEvent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .244 17.7.5 GetEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .245 17.7.6 WaitEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .246 17.7.7 Examples of Using Events . . . . . . . . . . . . . . . . . . . . . . . .247 17.8 Communication Management Services . . . . . . . . . . . . . . . . .249 17.8.1 Data Types and Identifiers . . . . . . . . . . . . . . . . . . . . . . . .249 17.8.2 SendMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .250 17.8.3 ReceiveMessage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .252 17.8.4 GetMessageResource. . . . . . . . . . . . . . . . . . . . . . . . . . . .253 17.8.5 ReleaseMessageResource . . . . . . . . . . . . . . . . . . . . . . . .254 17.8.6 GetMessageStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .255 17.8.7 Examples of Using Messages . . . . . . . . . . . . . . . . . . . . . .256 17.9 Operating System Execution Control . . . . . . . . . . . . . . . . . . .259 17.9.1 Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .259 17.9.2 GetActiveApplicationMode . . . . . . . . . . . . . . . . . . . . . . . .259 17.9.3 StartOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .260 17.9.4 ShutdownOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .260 17.9.5 Examples of Application Modes Usage. . . . . . . . . . . . . . .261 17.9.6 Hook Routines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .264 17.9.6.1 ErrorHook. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .264 17.9.6.2 PreTaskHook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .265 17.9.6.3 PostTaskHook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .266 17.9.6.4 IdleLoopHook. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .266 17.9.6.5 StartupHook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .267 17.9.6.6 ShutdownHook. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .268 Section 18. ORTI Implementation 18.1 Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .269 OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Table of Contents 13 A G R E E M E N T SetAbsAlarm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .235 CancelAlarm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .236 GetAlarmBase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .237 GetAlarm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .238 Examples for Counter and Alarm Management . . . . . . . .239 N O N - D I S C L O S U R E 17.6.10 17.6.11 17.6.12 17.6.13 17.6.14 R E Q U I R E D Table of Contents R E Q U I R E D Table of Contents 18.2 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .269 18.3 ORTI Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .271 18.3.1 ORTI Trace Interfaces. . . . . . . . . . . . . . . . . . . . . . . . . . . .271 18.3.2 ORTI Breakpoint Interface. . . . . . . . . . . . . . . . . . . . . . . . .273 18.4 ORTI Supporting OS Properties . . . . . . . . . . . . . . . . . . . . . . .274 18.5 ORTI Generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .275 A G R E E M E N T Appendix A. Sample Application A.1 Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .279 A.2 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .279 A.3 Source Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .280 Appendix B. System Service Timing B.1 Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .283 B.2 General Notes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .283 N O N - D I S C L O S U R E Appendix C. Memory Requirements C.1 Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .289 C.2 Memory for the OSEK Operating System. . . . . . . . . . . . . . . .289 C.3 Data Sheet for the Cosmic . . . . . . . . . . . . . . . . . . . . . . . . . . .292 Appendix D. System Generation Error Messages D.1 Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .297 D.2 Error Message Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .297 D.3 Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .297 D.4 Warning Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .314 Appendix E. Quick Reference E.1 Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .319 E.2 System Services Quick Reference . . . . . . . . . . . . . . . . . . . . .319 E.3 OIL language Quick Reference . . . . . . . . . . . . . . . . . . . . . . .325 E.3.1 OS Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .326 User's Manual 14 OSEK Operating System -- Rev 1.2 Table of Contents MOTOROLA E.3.2 E.3.3 E.3.4 E.3.5 E.3.6 E.3.7 E.3.8 E.3.9 TASK Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .345 ISR Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .347 STACK Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .347 RESOURCE Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .348 ALARM Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .348 COUNTER Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .349 MESSAGE Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .349 EVENT Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .351 N O N - D I S C L O S U R E A G R E E M E N T User's Manual Index R E Q U I R E D Table of Contents OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Table of Contents 15 N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Table of Contents User's Manual 16 OSEK Operating System -- Rev 1.2 Table of Contents MOTOROLA 3-1 4-1 4-2 4-3 4-4 4-5 4-6 4-7 4-8 4-9 4-10 5-1 5-2 7-1 8-1 8-2 9-1 9-2 10-1 11-1 14-1 15-1 18-1 Title Restricted upward compatibility for conformance classes . . 33 Task status model of an Extended Task with its task transitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 Task status model with task transitions for Basic Tasks . . . 44 Task management architecture . . . . . . . . . . . . . . . . . . . . . . 46 Task priorities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 Persistent task node assignment . . . . . . . . . . . . . . . . . . . . . 53 Task link table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 Fixed stack linked with the task node. . . . . . . . . . . . . . . . . . 56 Dynamic stack allocation from the stack pool . . . . . . . . . . . 57 Persistent stack allocation from the stack pool . . . . . . . . . . 58 Static stack allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Non-preemptive scheduling . . . . . . . . . . . . . . . . . . . . . . . . . 68 Full-preemptive scheduling . . . . . . . . . . . . . . . . . . . . . . . . . 69 Priority Ceiling Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Counters and alarms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 Two cases for the absolute alarm . . . . . . . . . . . . . . . . . . . . 98 Synchronization by events in case of full-preemptive scheduling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107 Synchronization by events in case of full-preemptive scheduling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108 Operations with Queued Messages . . . . . . . . . . . . . . . . . .116 System startup in the OSEK OS . . . . . . . . . . . . . . . . . . . .129 Application building process. . . . . . . . . . . . . . . . . . . . . . . .173 Banked Memory Model . . . . . . . . . . . . . . . . . . . . . . . . . . .185 Application Building Process with ORTI Support . . . . . . . .270 OSEK Operating System -- Rev 1.2 MOTOROLA Page User's Manual List of Figures 17 R E Q U I R E D Figure A G R E E M E N T List of Figures N O N - D I S C L O S U R E User's Manual -- OSEK Operating System N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D List of Figures User's Manual 18 OSEK Operating System -- Rev 1.2 List of Figures MOTOROLA 3-1 3-2 4-1 4-2 4-3 4-4 6-1 8-1 9-1 10-1 10-2 11-1 11-2 14-1 15-1 18-1 B-1 C-1 E-1 E-2 E-3 E-4 E-5 E-6 E-7 E-8 E-9 E-10 Title OSEK OS Conformance Classes . . . . . . . . . . . . . . . . . . . . . . 34 OSEK OS maximal system resources . . . . . . . . . . . . . . . . . . 35 States and status transitions in the case of Extended Tasks . 42 States and status transitions in the case of Basic Tasks . . . . 43 Task Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 Task Management Run-time Services . . . . . . . . . . . . . . . . . . 62 Interrupt Management Services in the OSEK OS . . . . . . . . . 81 Counter and Alarm Management Run-time Services . . . . . .102 Event Management Run-time Services . . . . . . . . . . . . . . . .109 Features of the Message Concept . . . . . . . . . . . . . . . . . . . .113 Task Management Run-time Services . . . . . . . . . . . . . . . . .119 OSEK OS system services for hook routines . . . . . . . . . . . .124 OSEK OS Error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . .127 System Generator command line options . . . . . . . . . . . . . .174 Parameters to define System Timer hardware . . . . . . . . . . .189 ORTI Generator Command Line Options . . . . . . . . . . . . . . .276 OSEKOS_20 version of the Operating System run-time services timing characteristics (HC12D60, Cosmic software) . . . . . .285 OSEKOS_20 version of the Operating System memory requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .292 OSEK OS services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .319 Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .322 Constructional elements . . . . . . . . . . . . . . . . . . . . . . . . . . . .323 OSEK Operating System run-time services return values and error values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .324 OSEK Operating System constants . . . . . . . . . . . . . . . . . . .325 OS Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .326 TASK Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .345 ISR Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .347 STACK Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .347 RESOURCE Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . .348 OSEK Operating System -- Rev 1.2 MOTOROLA Page User's Manual List of Tables 19 R E Q U I R E D Figure A G R E E M E N T List of Tables N O N - D I S C L O S U R E User's Manual -- OSEK Operating System R E Q U I R E D List of Tables ALARM Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .348 COUNTER Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . .349 MESSAGE Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . .349 EVENT Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .351 N O N - D I S C L O S U R E A G R E E M E N T E-11 E-12 E-13 E-14 User's Manual 20 OSEK Operating System -- Rev 1.2 List of Tables MOTOROLA OSEK OS conforms to the following requirements: * OS is fully configured and statically scaled; * OSEK OS is a ROM-able system, i.e. the OS code may be executed from Read-Only-Memory. OSEK OS may be placed into chip memory during manufacture, and users' applications may be added during development time; * OS performance parameters are well known; * Being written in strict correspondence with ANSI C standard, the OS and application on its basis can be easily ported from one platform to another. A wide range of scalability, a set of system services, various scheduling mechanisms, and convenient configuration features make the OSEK Operating System feasible for a broad spectrum of applications and hardware platforms. The OSEK OS provides a pool of different services and processing mechanisms for task management and synchronization, data exchange, resource management, and interrupt handling. The following features are granted to the user: 1. The term OSEK means `Offene Systeme und deren Schnittstellen fur die Elektronik im Kraftfahrzeug' (Open systems and the corresponding interfaces for automotive electronics). A realtime operating system, software interfaces and functions for communication and network management tasks are thus jointly specified within the OSEK standard. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Overview 21 R E Q U I R E D OSEK1 Operating System (OSEK OS) is a real-time operating system which conforms to the specification of the OSEK/VDX Operating System version 2.0, revision 1, 15 October 1997. A G R E E M E N T Section 1. Overview N O N - D I S C L O S U R E User's Manual -- OSEK Operating System R E Q U I R E D Overview Task Management * Activation and termination of tasks; * Management of task states, task switch. Scheduling Policies * Full-, non-, and mixed-preemptive scheduling techniques. A G R E E M E N T Event Control * Event Control for task synchronization. Interrupt Management * Services for hardware interrupt flag manipulations; * Frames for interrupt service routines. Resource Management * Mutually exclusive access control for inseparable operations to jointly used resources or devices, or for control of a program flow. N O N - D I S C L O S U R E Communication1 * Unqueued Message: Data exchange without buffering; * Queued Message: Data exchange with buffering. Counter2 and alarm management * Counter management provides services for execution of recurring events; * Alarm management is based on counter management. It enables entry of (cyclic) alarm requests. The expiration of a preset relative counter value, or the fact that a preset absolute counter value is reached, results in activation of a task, or setting of a task event. 1. Communication part of OSEK Operating System conforms the specification of the OSEK Communication System, version 2.1, revision 1, 17 June 1998. 2. Counter Management part of OSEK Operating System conforms the specification of the OSEK Operating System Application Program Interface version 1.00, 11 September 1995. User's Manual 22 OSEK Operating System -- Rev 1.2 Overview MOTOROLA Mechanism supporting the user in various error classes. ORTI Subsystem * ORTI provides interface to Operating System run-time data for "OSEK aware" debuggers. OSEK Operating System is scaled in two ways - either by changing the set of system services or via the so-called Conformance Classes. They are available to satisfy different requirements concerning functionality and capability of the OS. These Conformance Classes do not only differ concerning the number of services they provide, but also with regard to their capabilities and scalability. The classes are based on one another in upwardly compatible fashion. The Conformance Classes are generated by meaningful grouping of services (see Section 3.3 Conformance Classes). The OSEK OS is built according to the user's configuration instructions at system generation time. Both system and application parameters are configured statically. Therefore, a special tool called the System Generator is used for this purpose. Special statements are designed to tune any parameter. The user must only edit the definition file, run System Generator and then assemble resulting files with application files. Thus, the user can adapt the Operating System to the control task and the target hardware. OS cannot be modified later at execution time. OSEK Operating System is well documented and measured. In the User's Manual, all system mechanisms, particularities, services and programming techniques are described in detail with numerous examples. Numbers for performance characteristics and memory requirements are provided. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Overview 23 A G R E E M E N T * N O N - D I S C L O S U R E Error treatment R E Q U I R E D Overview N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Overview User's Manual 24 OSEK Operating System -- Rev 1.2 Overview MOTOROLA 2.2 Manual Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 2.3 Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 2.4 Definitions, Acronyms and Abbreviations . . . . . . . . . . . . . . . . . 27 2.5 Installation Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 2.6 Technical Support Information . . . . . . . . . . . . . . . . . . . . . . . . . 29 2.2 Manual Structure This User's Manual consists of the following sections: Section 1 Overview describes what the OSEK OS is and highlights its basic features. Section 2 Notation contains a description of the Manual structure, typographical conventions and the list of acronyms. Section 3 Operating System Architecture gives a high level description of OS architecture and presents OS Conformance Classes. Section 4 Task Management explains the task concept in OSEK and all other questions related to tasks. Section 5 Scheduler provides a description of scheduling policies in OSEK OS. Section 6 Interrupt Processing highlights the OSEK approach to interrupt handling. Section 7 Resource Management describes resource management and task coordination by resources. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Notation 25 R E Q U I R E D 2.1 Contents A G R E E M E N T Section 2. Notation N O N - D I S C L O S U R E User's Manual -- OSEK Operating System R E Q U I R E D Notation Section 8 Counters and Alarms describes usage of these control mechanisms in OSEK OS. Section 9 Events is devoted to event management and task coordination by events. Section 10 Communication describes message concept in OSEK and their usage. A G R E E M E N T Section 11 Error Handling and Special Routines describes support provided to the user to debug an application and handle errors. Section 12 System Configuration describes possible OSEK OS versions, configuration options and the configuration mechanism. Section 14 Building of Application contains information on how to build an user's application using OSEK OS. It also describes memory requirements. Section 15 HC12 Platform-Specific Features discusses special OSEK OS features for different MCU types and issues connected with porting applications to these MCUs. N O N - D I S C L O S U R E Section 16 Application Troubleshooting contains useful information for debugging applications developed using OSEK OS. Section 17 System Services provides a detailed description for all OSEK Operating System run-time services, with appropriate examples. Section 18 ORTI Implementation provides information about preparation all data needed for OSEK aware debugger to display information about application in OSEK terms. Appendix A Sample Application contains the text and listing of a sample customer application developed using OSEK OS. Appendix B System Service Timing provides information about OS services execution time. Appendix C Memory Requirements provides information about the amount of ROM and RAM directly used by various versions of the OSEK OS. User's Manual 26 OSEK Operating System -- Rev 1.2 Notation MOTOROLA Appendix D System Generation Error Messages explains OSEK OS System Generator error messages. Appendix E Quick Reference briefly lists all OSEK OS run-time services, with entry and exit conditions. 2.3 Typographical Conventions R E Q U I R E D Notation Typographical Conventions Bold is used for important terms, notes and warnings. Italics Italics are used for all OSEK names of directives, macros, constants, routines and variables. Courier font Courier typeface is used for code examples in the text. Courier Italic Courier Italic typeface is used for OSEK terms when these are first introduced. 2.4 Definitions, Acronyms and Abbreviations API Application Program Interface (a set of data types and functions) BCC Basic Conformance Class, a defined set of functionality in OSEK, for which the waiting state of tasks is not permitted BT Basic task (task, which never has the waiting state) CPU Central Processor Unit ECC Extended Conformance Class, a defined set of functionality in OSEK, for which the waiting state of tasks is permitted ECU Electronic Control Unit (similar to MCU) ET Extended Task (task, which may have the waiting state) OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Notation 27 N O N - D I S C L O S U R E boldface type A G R E E M E N T This manual employs the following typographical conventions: N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Notation ID Identifier, an abstract identifier of a system object ISF Interrupt Stack Frame, a stacked model of CPU registers, produced by CPU hardware and/or software instructions during CPU interrupt ISR Interrupt Service Routine MCU Microcontroller Unit (Motorola's microcontrollers) MO Message object N/A Not applicable OIL OSEK Implementation Language ORTI OrtiGen OS OSEK OSEKOS_20 OSEK Run Time Interface ORTI Generator Utility Operating System, a part of the OSEK Open systems and their corresponding interfaces for automotive electronics (in German) Implementation of the OSEK OS according to "OSEK/VDX Operating System", Version 2.0 Revision 1, 15 October 1997 RAM Random Access Memory ROM Read Only Memory SG, SysGen System Generator 2.5 Installation Instructions 2.5.1 Required Environment This version of the product is to be used on an IBM PC 486 (and higher) compatible. To install and evaluate the product, you require approximately 4 MB of hard disk space. The PC must work under MS Windows 95 or Windows NT 4.0 during OSEK installation. To use OSEK OS after installation install the Cross Compiler on your computer (See Section 15 for more information). You must call the DOS prompt under Windows NT to run the NMAKE utility. All supplied makefiles are developed for the Microsoft C++ NMAKE utility. User's Manual 28 OSEK Operating System -- Rev 1.2 Notation MOTOROLA 2.5.2 Installation To setup OSEK OS on your hard drive: 1. Insert the installation disk into a 3.5" floppy drive. The following instructions assume that the drive letter is a:. If another drive is chosen, substitute that drive letter where appropriate. 2. Run the A:\SETUP.EXE program either from the File Manager or Program Manager. R E Q U I R E D Notation Technical Support Information After installation, the hard drive should contain the root directory of OSEK which contains a set of files in the following subdirectories: * BIN System Generator * INC Operating System header files * SRC Operating System source files * HWSPEC Hardware specific files (usually startup and vector table files) * SAMPLE OSEK Operating System Sample application * MAN User's Documentation There is a file titled FILELIST.TXT file in the OSEK OS root directory. This document contains a complete list of files included in this release. 2.6 Technical Support Information For additional product or support information please contact your local Motorola Sales Office. Alternatively, use the following contact methods: Email: osek@helpline.sps.mot.com Phone: +44 13 55 35 53 98 (English) +49 89 92 10 38 83 (German or English) OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Notation 29 N O N - D I S C L O S U R E 4. After installation verify the consistency of the package by means of comparing the real set of files and directories with the list in FILELIST.TXT file. A G R E E M E N T 3. Follow the prompts and instructions of the installation program. R E Q U I R E D Notation +44 13 55 26 52 01 (English) +49 89 92 10 38 20 (German or English) N O N - D I S C L O S U R E A G R E E M E N T Fax: User's Manual 30 OSEK Operating System -- Rev 1.2 Notation MOTOROLA 3.2 Processing Levels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 3.3 Conformance Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 3.4 OSEK OS Overall Architecture . . . . . . . . . . . . . . . . . . . . . . . . . 35 3.5 Application Program Interface . . . . . . . . . . . . . . . . . . . . . . . . . 37 3.2 Processing Levels The OSEK Operating System provides a pool of different services and processing mechanisms. It serves as a basis for application programs which are independent of each other, and provides their environment on a processor. The OSEK OS enables a controlled real-time execution of several processes which virtually run in parallel. The OSEK Operating System provides a defined set of interfaces for the user. These interfaces are used by entities which are competing for the CPU. There are two types of entities: * Interrupts (service routines managed by the Operating System); * Tasks (basic tasks and extended tasks). The highest processing priority is assigned to the interrupt level, where interrupt service routines (ISR) are executed. Interrupt services may call a number of operating system services. The processing level of the operating system has a priority ranking immediately below the former one. This is the level on which the operating system works: task management procedures, scheduler and system services. Just below this is the task level on which the application software is executed. Tasks are executed according to their user assigned priority. A distinction is OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Operating System Architecture 31 R E Q U I R E D 3.1 Contents A G R E E M E N T Section 3. Operating System Architecture N O N - D I S C L O S U R E User's Manual -- OSEK Operating System made between the management of tasks with and without waiting state (Extended and Basic Tasks, see Section 4.2 Task Concept). The run time context refers to resources which are occupied at the beginning of execution time and are released again once the task is finished. The following priority rules have been established: * Interrupts have precedence over tasks; * The interrupt priority is defined by specific hardware conditions; * For items handled by the OS, bigger numbers refer to higher priorities; * The task's priority is statically assigned by the user. The Operating System provides services and ensures compliance with the priority rules mentioned above. 3.3 Conformance Classes Various requirements of the application software for the system, and various capabilities of a specific system (e.g. processor type, amount of memory) demand different features of the operating system. These operating system features are described as Conformance Classes (CC). They differ in the number of services provided, their capabilities and different types of tasks. N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Operating System Architecture Conformance classes were created to support the following objectives: * To provide convenient groups of operating system features for easier understanding and discussion of the OSEK operating system. * To allow partial implementations along pre-defined lines. These partial implementations may be certified as OSEK compliant. * To create un upgrade path from classes of lesser functionality to classes of higher functionality with no changes to the application using OSEK related features. The desired Conformance Class is selected by the user at system generation time and cannot be changed during execution. User's Manual 32 OSEK Operating System -- Rev 1.2 Operating System Architecture MOTOROLA The definition of the functionalities provided by each Conformance Class depends on the properties of the tasks and on the scheduling behavior. As the task properties (Basic or Extended, see Section 4.3 Task State Model) have a distinct influence on CC, they also assume part of their names. There are Basic-CC and Extended-CC, and each of these groups can have various "derivatives". Multiply requesting of task activation (see Section 4.4 Task Activation and Termination); * Task types (see Section 4.3 Task State Model); * Number of tasks per priority. 1 task/priority no multiply activations >1 task/priority multiply activations for basic tasks only BT only BT and ET BCC1 ECC1 BCC2 ECC2 Figure 3-1. Restricted upward compatibility for conformance classes The following Conformance Classes are defined in the OSEK OS: BCC1, BCC2, ECC1, ECC2. * BCC1 - only Basic tasks, limited to one request per task and one task per priority, while all tasks have different priorities; * BCC2 - like BCC1, more than one task per priority possible and multiple activation admissible; * ECC1 - like BCC1, plus Extended tasks; * ECC2 - like BCC2, plus Extended tasks without multiply activation admissible. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Operating System Architecture 33 N O N - D I S C L O S U R E * A G R E E M E N T Conformance classes are determined by the following attributes: R E Q U I R E D Operating System Architecture Conformance Classes R E Q U I R E D Operating System Architecture BCC1 defines the minimum Conformance Class of the OSEK OS, ECC2 defines its maximum CC. Multiple activations means that the OSEK OS receives and records activations (even multiple activations) of a task already activated. A G R E E M E N T In the OSEK OS the number of task multiply activations is defined in a basic task specific attribute during system generation. If the maximum number of multiply activations has not been reached, the activation of the basic task is queued in a Scheduler queue to preserve task activation order. Table 3-1 presents minimum resources to which an application may resort, determined for each Conformance Class in the OSEK OS. Table 3-1. OSEK OS Conformance Classes Multiple activation of tasks BCC1 BCC2 ECC1 ECC2 no yes BT: no, ET: no BT: yes, ET: no Number of tasks which are not in the suspended state Number of tasks per priority 1 N O N - D I S C L O S U R E Number of events per task >1 1 (both BT/ET) >1 (both BT/ET) BT: no ET: >= 8 - Number of priority classes Resources >= 16, any combination of BT/ET >=8 >=8 only Scheduler >= 8 resources (including Scheduler) Alarm >= 1 single or cyclic alarm Messages possible The system configuration option CC (specified by the user) defines the class of the overall system. This option can have values BCC1, BCC2, ECC1, ECC2 (see Section 13.3 OS Definition). It is impossible to have tasks of different Conformance Classes in one application! All tasks must strictly conform to the Conformance Class specified at the system configuration stage. User's Manual 34 OSEK Operating System -- Rev 1.2 Operating System Architecture MOTOROLA R E Q U I R E D Operating System Architecture OSEK OS Overall Architecture Table 3-2 presents maximal values for system resources: Table 3-2. OSEK OS maximal system resources BCC1 BCC2 ECC1 ECC2 Number of tasks which are not in the suspended state limited only to RAM and/or ROM available(1) Number of tasks per priority limited only to RAM available Number of events per task limited only to RAM and/or ROM available(3) Alarm limited only to RAM and/or ROM available Messages limited only to RAM and/or ROM available 1. See Appendix C Memory Requirements for memory consumption numbers. 2. Keeping this value allows a byte to be used which improves RAM and ROM requirements and execution speed. 3. In case of using resource access check, number of resources is limited to 8, including Scheduler. This corresponds to the following system configuration: STATUS = EXTENDED, Resources = TRUE, ResourceAccessCheck = TRUE, FastResource = FALSE (see Section 13.3 OS Definition for the details of system configuration). 3.4 OSEK OS Overall Architecture The OSEK OS is a real-time operating system, which is executed within a single electronic control unit. It provides local services for user's tasks. The OSEK OS consists of the following components: * Scheduler - controls the allocation of the CPU to the different tasks; * Task management - provides operations with tasks; * ISR management - provides entry/exit frames for interrupt service routines and supports CPU interrupt flag manipulation; * Resource management - supports a special kind of semaphore for mutually exclusive access to shared resources; OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Operating System Architecture 35 N O N - D I S C L O S U R E only Scheduler A G R E E M E N T 256(2) Number of priority classes Resources BT: ET: 8(2) - A G R E E M E N T R E Q U I R E D Operating System Architecture * Local communication - provides message exchange between tasks; * Counter management - provides operations on objects like timers and incremental counters; * Alarm management - links the tasks and counters; * Error handlers - handle the user's application errors and internal errors, and provide recovery from the error conditions; * Hook routines - provide additional debugging features * System start-up - initializes the data and starts the execution of the applications; * System timer - provides implementation-independent time management. N O N - D I S C L O S U R E As you have seen in Table 3-1, Conformance Classes, in general, differ in the degree of services provided for the task management and scheduling (number of tasks per priority, multiple requesting, Basic/Extended Tasks). In higher CC advanced functionality is added for resource management and event management only. But even in the lowest BCC1 the user is provided with merely all OSEK OS service mechanisms. The OSEK Operating System is scaled not only via Conformance Classes but it also has many various extensions which can be in any Conformance Class. These extensions affect memory requirements and overall system performance. The extensions can be turned on or turned off with the help of the corresponding system configuration options. These are all described in Section 12 System Configuration. Since the OSEK Operating System is fully statically configured, the configuration process is supported by the System Generator (SG). This is a command-line utility, which processes system generation statements defined by the user in the special file. These statements fully describe the desired system features and application object's parameters. SG produces C-code that is to be compiled together with other user's source code. The produced code consists of C-language definitions and declarations of data as well as C-preprocessor directives. See User's Manual 36 OSEK Operating System -- Rev 1.2 Operating System Architecture MOTOROLA The OSEK Operating System establishes the Application Program Interface (API) which must be used for all user actions connected with system calls and system objects. This API defines data types used by the system, the syntax of all run-time service calls, declarations and definitions of the system. OSEK OS data types are described in subsections dedicated to the corresponding mechanisms. Syntax of system calls and system configuration statements are described briefly in corresponding subsections and in detail in Section 12 System Configuration and Section 17 System Services. NOTE: The user's source code shall strictly correspond to the rules presented in this Manual. The OSEK OS can has the Extended Status. It means that additional checking is made inside all OS activities and extended return codes are returned by all OS services to indicate errors if they have occurred. See Section 17 System Services and Section 11.4 Error Handling about Extended Status return values. To provide the Extended Status in the system, the configuration option STATUS must be set to EXTENDED at the configuration stage. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Operating System Architecture 37 A G R E E M E N T 3.5 Application Program Interface N O N - D I S C L O S U R E Section 12 System Configuration and Section 14 Building of Application for details about system generation. R E Q U I R E D Operating System Architecture Application Program Interface N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Operating System Architecture User's Manual 38 OSEK Operating System -- Rev 1.2 Operating System Architecture MOTOROLA 4.2 Task Concept . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 4.3 Task State Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 4.4 Task Activation and Termination . . . . . . . . . . . . . . . . . . . . . . . 44 4.5 Task Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 4.6 Task Priorities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 4.7 Task Related Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 4.8 Programming Issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 4.2 Task Concept Complex control software can conveniently be subdivided into parts executed according to their real-time requirements. These parts can be implemented by means of tasks. A task provides the framework for the execution of functions. The Operating System provides parallel and asynchronous task execution organization by the scheduler. OSEK OS provides a set of tools for the user to manage tasks. They are activated before their execution - memory resources needed for a task are allocated. Tasks may be terminated after necessary actions are performed - memory resources are released. After a task is activated, it may run and terminate or it may be implemented in an endless loop with at least one synchronizing system call. It is not possible to run several parallel endless loops without switching mechanism (scheduler). Tasks can be switched during their execution from one to another, or may be interrupted by ISR. If no task is active, only the scheduler idle loop runs (see Section 5.2 General). Task states and transitions between them are discussed in Section 4.3 Task State Model. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Task Management 39 R E Q U I R E D 4.1 Contents A G R E E M E N T Section 4. Task Management N O N - D I S C L O S U R E User's Manual -- OSEK Operating System R E Q U I R E D Task Management Two different task concepts are provided by the OSEK OS: * Basic Tasks (BT); * Extended Tasks (ET). A G R E E M E N T Basic Tasks only release the processor, if: * they are being terminated, * the OSEK OS is executing higher-priority tasks, or * interrupts occur which cause the processor to switch to an interrupt service routine. Extended Tasks are distinguished from Basic Tasks by being allowed to use additional operating system services which may result in a waiting state. The waiting state allows the processor to be freed and to be reassigned to a lower-priority task without the need to terminate the Extended Task. Both kinds of tasks have their advantages which must be compared, application dependent. They are both justified and are supported by the OSEK operating system. N O N - D I S C L O S U R E Each task has a set of data related to it - a task descriptor located in ROM (task configuration table) and a task control block in RAM (task node) for activated tasks. Also, each task has its own stack assigned. See Section 4.7 Task Related Resources about the task control block, the task configuration table and the task stack. Every running task is represented by its run time context. This refers to CPU registers and some compiler-dependent `pseudoregisters' in RAM. When the task is interrupted or preempted by another task, the run time context is saved in the task's stack. Run time context differs for nonpreemptive and preemptive tasks; for preemptive tasks, more RAM is required to save the context. Therefore, for a mixed-preemptive system (it means that both non-preemptive and preemptive tasks can exist in the system, see Section 5.3 Scheduling Policy) a distinction can be made by the Operating System between these types of contexts. It is controlled by the UseSameContext configuration option. In the case where different contexts are saved for non-preemptive and preemptive tasks, the OS must perform additional code to distinguish the task type. User's Manual 40 OSEK Operating System -- Rev 1.2 Task Management MOTOROLA A task can be in several states since the processor can only execute one instruction of a task at any point in time, but several tasks may be competing for the processor at the same time. The OSEK OS is responsible for saving and restoring task context in conjunction with state transitions whenever necessary. 4.3.1 Extended Tasks Extended Tasks have four task states: * running In the running state, the CPU is assigned to the task, so that its instructions can be executed. Only one task can be in this state at any point in time, while all the other states can be adopted simultaneously by several tasks. * ready All functional prerequisites for a transition into the running state exist, and the task only waits for allocation of the processor. The scheduler decides which ready task is executed next. * waiting A task cannot be executed (any longer), because it has to wait for at least one event (see Section 9 Events). * suspended In the suspended state, the task is passive and does not occupy any resources, merely ROM. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Task Management 41 A G R E E M E N T 4.3 Task State Model N O N - D I S C L O S U R E Otherwise, some more RAM is required to store the `full' context for nonpreemptive tasks too. The use of this option is application dependent. R E Q U I R E D Task Management Task State Model R E Q U I R E D Task Management running wait A G R E E M E N T waiting terminate preempt start suspended activate release ready Figure 4-1. Task status model of an Extended Task with its task transitions N O N - D I S C L O S U R E Table 4-1. States and status transitions in the case of Extended Tasks Transition Former state New state Description activate suspended ready A new task is entered into the ready list by a system service. start ready running A ready task selected by the scheduler is executed. wait running waiting To be able to continue operation, the running task requires an event. It causes its transition into the waiting state by using a system service. release waiting ready Events have occurred on which a task has waited. preempt running ready The scheduler decides to start another task. The running task is put into the ready state. terminate running suspended The running task causes its transition into the suspended state by a system service. Termination of tasks is only possible if the task terminates itself (`selftermination'). This restriction is to avoid complex book-keeping of resources dynamically allocated by the task. User's Manual 42 OSEK Operating System -- Rev 1.2 Task Management MOTOROLA The state model of Basic Tasks is nearly identical to the Extended Tasks state model. The only exception is that Basic Tasks do not have a waiting state. * running In the running state, the CPU is assigned to the task so that its instructions can be executed. Only one task can be in this state at any point in time, while all the other states can be adopted simultaneously by several tasks. * ready All functional prerequisites for a transition into the running state exist, and the task only waits for allocation of the processor. The scheduler decides which ready task is executed next. * suspended In the suspended state, the task is passive and does not occupy any resources, merely ROM. Table 4-2. States and status transitions in the case of Basic Tasks Transition Former state New state Description activate suspended ready A new task is entered into the ready list by a system service. start ready running A ready task selected by the scheduler is executed. preempt running ready terminate running suspended The scheduler decides to start another task. The running task is put into the ready state. The running task causes its transition into the suspended state by a system service. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Task Management 43 A G R E E M E N T 4.3.2 Basic Tasks N O N - D I S C L O S U R E There is no provision for a direct transition from the suspended state into the waiting state. This transition is redundant and would add to the complexity of the scheduler. The waiting state is not directly entered from the suspended state since the task starts and explicitly enters the waiting state on its own. R E Q U I R E D Task Management Task State Model R E Q U I R E D Task Management running terminate A G R E E M E N T preempt start suspended activate ready Figure 4-2. Task status model with task transitions for Basic Tasks N O N - D I S C L O S U R E 4.4 Task Activation and Termination Depending on the Conformance Class, a task can be activated single or multiple. The difference between single and multiple activation is that: * For of a task suited for multiple activation, all task activations are noted down. It means that whenever a task is activated by the application, the appropriate task is started at the next possible time, even if it is already running while the request is issued. In such cases, the request is saved by the operating system, so the task can be started again by the operating system once it has been terminated. This procedure is repeated several times until all requests have been completed. In the OSEK OS the activation of the basic task is queued in Scheduler queues to preserve task activation order. User's Manual 44 OSEK Operating System -- Rev 1.2 Task Management MOTOROLA Multiple activation property exists only for BCC2 and ECC2 Conformance Classes. It is possible to turn it off via the system configuration option MultiplyActivation. OSEK OS uses the scheme of task activation and termination as shown on Figure 4-3. This idea allows dynamic memory reallocation which provides economical consumption of resources. During task activation the ActivateTask service analyzes the task configuration table of the task to be activated, and allocates a stack buffer and a task node as specified in the task configuration table. In the figure the typical allocation method is shown - a stack buffer is retrieved from the stack pool and a task node from the scheduler's list of free task nodes. If these resources are available, then the task node is initialized and inserted into the scheduler's queues to be dispatched. If the task does not have multiply activation requests, then the TerminateTask and ChainTask services release both the task node and the stack buffer and return them to the system for re-use. If a task has multiple activation requests, then TerminateTask and ChainTask services do not release the task node and the stack buffer because these structures will be used for task reactivation. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Task Management 45 A G R E E M E N T In the case of a task suited for single activation, either the task activation is noted down, or, if the task has already been requested, nothing happens. N O N - D I S C L O S U R E * R E Q U I R E D Task Management Task Activation and Termination R E Q U I R E D Task Management Stack pools Task nodes (control blocks) Task configuration tables Task configuration table Free task node A G R E E M E N T Stack buffer Activate task Terminate task Initialized task mode Running task mode Scheduler queues Figure 4-3. Task management architecture N O N - D I S C L O S U R E Hence, task activation may be considered as dynamic resource allocation, because task control blocks and stack pools are allocated dynamically. This approach allows the optimization of resource usage, because one resource (for instance, a task control block) may be used by different tasks at different times. But, in the case where requested resources aren't available, it may lead to indeterministic behavior of the operating system. This situation may occur when too many tasks are activated. To avoid that weakness, the user is also allowed to statically assign task control blocks and stack areas for critical tasks. Such explicitly defined resources are held by a task for the application life time. In this case, the task control block and/or the task stack are not released and cannot be re-assigned for other tasks. User's Manual 46 OSEK Operating System -- Rev 1.2 Task Management MOTOROLA Table 4-3. Task Properties Property Name TYPE Property Value BASIC EXTENDED SCHEDULE Description Basic task Extended task NON Non-preemptive task FULL Preemptive task AUTOSTART TRUE/FALSE Activate the task at system start-up PersistentNode TRUE/FALSE A persistent task control block is assigned (linked with the task configuration tables) POOLSTACK A stack should be allocated to the task during task activation - dynamic stack allocation from the stack pool OWNSTACK A stack is explicitly assigned to the task (address of the top of the stack is included in the task configuration table) NODESTACK A task node stack is implicitly assigned to be used by the task (during the task activation) TRUE/FALSE A persistent stack from the stack pool (the pool identifier is included in the task configuration table) StackMethod PersistentStack 4.6 Task Priorities OSEK OS specifies the value 0 as the lowest priority in the operating system. Accordingly bigger numbers define higher priorities. In OSEK OS a priority is statically assigned to each task and it cannot be changed by the user at the execution time. Some Conformance Classes permit several tasks of the same priority level (see Section 3-1 OSEK OS Conformance Classes). A dynamic priority management is not OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Task Management 47 A G R E E M E N T In OSEK OS every task is characterized by the set of properties. These properties define the task behavior and resource allocation method. Each task property has its own name, and the user defines the task features by setting the corresponding properties in the task definition. See Section 12 System Configuration about task definition. The list of possible task properties is provided in Table 4-3. N O N - D I S C L O S U R E 4.5 Task Properties R E Q U I R E D Task Management Task Properties R E Q U I R E D Task Management supported. However, in particular cases the operating system can treat a task with a defined higher priority. In this context, please refer to Section 7.3.1 Priority Ceiling Protocol. On the basis of the task priority the scheduler decides which is the next of the ready tasks to be transferred into the running state. Tasks are started depending on their order of activation, according to the FIFO mechanism, whereby an Extended Task in the waiting state does not block the start of subsequent tasks of identical priority. A G R E E M E N T A preempted task is considered to be the oldest task in the ready list of its current priority. A task being released from the waiting state is treated like the newest task in the ready list of its priority. Figure 4-4 illustrates how tasks priorities affect the order of their execution . N N O N - D I S C L O S U R E FIFO list of ready tasks 3 2 1 0 *** high scheduler low priority > > these tasks will be executed in turn later search the next task to be processed actually processed CPU and terminated task (with priority N) scheduler next running task processor time Figure 4-4. Task priorities User's Manual 48 OSEK Operating System -- Rev 1.2 Task Management MOTOROLA 1. The scheduler searches for all tasks in the ready state. 2. From the set of ready tasks, the scheduler determines the set of tasks with the highest priority. 3. Within the set of tasks in the ready state and of the highest priority, the scheduler finds the task that has been in the ready state the longest time (`oldest' task). 4.7 Task Related Resources Each task has a task configuration table in ROM and task control block (task node) and task stack in RAM (during the task run time, if they are not assigned statically). These resources uniquely define task properties and the task run-time context. Also, at run-time the task link table exists in RAM to provide the correspondence between the task control block and the task configuration table. 4.7.1 Task Configuration Table The ROM-based task configuration table contains a static task description. This table holds all the information describing the task's properties and serves to initialize the RAM-based task control block during task activation. The task configuration table contains the following data: OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Task Management 49 A G R E E M E N T Thus, the following three steps are made to switch to the next running task: N O N - D I S C L O S U R E Several tasks of different priorities are in the ready state - three tasks of priority 3, one of priority 2, one of priority 1, and two priority 0 tasks. The task that has waited the longest time, depending of its order of requesting, is shown at the bottom of each FIFO queue. The CPU has just processed and terminated a task with priority N. The scheduler selects the next task to be processed (priority 3, first FIFO location). Before priority 2 tasks can be processed, all tasks of higher priority must have been executed completely. R E Q U I R E D Task Management Task Related Resources N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Task Management * Task properties (see Table 4-3) which define a run-time behavior of the task, as well as task activation parameters. The main properties are whether it is a Basic/Extended task (for the extended Conformance Classes only) or a preemptive/nonpreemptive task (for a mixed-preemptive scheduling policy). The properties also specify the source of the stack for the task, and the assignment of the task control block; * OS internal priority of the task1; * User defined priority of the task; * The hardware memory bank of the task2. If banked memory model is not supported (the HCBankCode system configuration option is turned off) this field is absent in the task configuration table; * The starting interrupt mask of the task. This field is absent if interrupt mask control is not supported; * The program counter value (the entry point) of the task; * The address of the persistent task node, that is a task node that is permanently assigned to the task (see Section 4.7.2 Task Control Block). This field is absent if persistent task control blocks are not supported in the system; * The address of the task stack source, i.e. the address of the stack pool or the constant address of the own task stack (see Section 4.7.4 Task Stack). This field is absent if all tasks use only node stacks. * The maximum number of the task multiply activations. * The address of the element of the task link table (see Section 4.7.3 Task Link Table). This field is absent if the simplified scheduler is used in the system (see Section 5.2.1 Simple Scheduler) or the system configuration option TaskIndexMethod is off and task multiple activation is not supported. 1. OSEK OS uses internal task priority during run-time. This priority is calculated by OSEK OS SysGen tool during application configuration. It may differ from user-defined task priority as a result of optimization. 2. This property is not used in current version of OSEK OS. User's Manual 50 OSEK Operating System -- Rev 1.2 Task Management MOTOROLA A RAM-based task control block (task node) serves as a dynamic descriptor of the task. It is valid only during task execution, that is when the task is not in the suspended state. Except persistent node assignment (see Section 4.7.2.1 Persistent Node Assignment), this task control block is linked to the scheduler's list of free nodes when it is not assigned to the task. In general, this block is allocated to the task during task activation, and it is initialized at that moment (see Figure 43). The task control block contains the following data: * A pointer for linking the task control block into scheduler queues. This field is absent if the simplified scheduler is used in the system; * The current task status. Some of the status bits are copied from the task property bits of the task configuration table. Other bits are: - a task waiting bit, which is set when the task is waiting for an event(s); - a scheduler bit, which is set when the task occupies the scheduler. * The current task priority. In general, the current priority may differ from the starting priority (located in the task configuration table) during the periods of time when the task occupies the resources, see Section 7.3.1 Priority Ceiling Protocol.This field is absent if the simplified scheduler is used in the system; * A pointer to the task configuration table; * The task context (for non-preemptive tasks), or a pointer to the stack frame, where the context is saved (for preemptive tasks). Note, that for mixed-preemptive scheduling systems, both non- OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Task Management 51 A G R E E M E N T 4.7.2 Task Control Block N O N - D I S C L O S U R E Some of these parameters are specified by the user during system configuration by means of the TASK object definition, while others are generated automatically. See Section 12 System Configuration and Section 14 Building of Application about system configuration and building an application. R E Q U I R E D Task Management Task Related Resources R E Q U I R E D Task Management N O N - D I S C L O S U R E A G R E E M E N T preemptive context and a pointer to the preemptive context are defined if the system configuration option UseSameContext is turned on. Otherwise, the preemptive context is used for nonpreemptive tasks also; * Two fields for event control in Extended Classes of the system. The first field contains the mask of the events the task is waiting for, while the second field contains the mask of the events that are set for the task (see Section 9 Events). If event management is not supported, these fields are absent; * The pointer to the head of the list of resources occupied by the task (if resource management is supported and the system property FastResource is turned off, see Section 7 Resource Management); * The address of the stack buffer allocated to the task. It is used during task termination when task management returns this stack buffer into the stack pool. If stack pools are not supported in the system then this field is absent; * The address of the task node stack or address of the persistent task stack if persistent node assignment is supported by the system. This field is absent if neither task node stacks nor persistent stacks are used; * The real address of the top of the task stack. This field is absent if multiple activation is not supported and the system configuration option ChainTaskItself is turned off. The task control block size depends on the system configuration and task properties. See Appendix B System Service Timing 4.7.2.1 Persistent Node Assignment The task control block may be statically assigned to the task. This mechanism prevents a task activation failure due to missing free task nodes and increases the speed of task activation/termination operations by means of excluding a task node queue manipulation. This mechanism is called persistent task node assignment, and it is illustrated in Figure 4-5. To define persistent node assignment for the task, the task property PersistentNode must be set in the TASK definition for this User's Manual 52 OSEK Operating System -- Rev 1.2 Task Management MOTOROLA Persistent task node assignment may be used in combination with any of the stack allocation options (see Section 4.7.4 Task Stack). Task configuration table #1 Task nodes array Free task node #1 Free task node #2 Task configuration table #2 Persistent task node #3 the task node address Free task node #4 Activate task Figure 4-5. Persistent task node assignment 4.7.3 Task Link Table Every task in the system is defined via the ROM-based task configuration table. When a task is activated, the task allocates a task node, and the address of the task configuration table is stored in the task OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Task Management 53 A G R E E M E N T As it is in the figure, task#2 has persistent task node#3 assigned to this task. Therefore, this task control block cannot be used by any other task in the system, and is not linked into the scheduler's list of free nodes when task#2 is not activated (not used). This task node is exclusively assigned for use by task#2. On the other hand, task#1 may use any of task nodes #1, #2 or #4, if they are free while task#2 is activated. N O N - D I S C L O S U R E task and the system configuration option PersistentNode must be turned on. R E Q U I R E D Task Management Task Related Resources R E Q U I R E D Task Management node. To accelerate the procedure of run-time task referencing, the system supports a special RAM-based vector of the links between the task configuration tables and task nodes. This vector is called the task link table. It serves for fast access to the task configuration table and the corresponding task control block during operations which reference to a task. A G R E E M E N T The task link table is illustrated in the figure below: Task configuration tables Task nodes Task node #1 Task #1 Task link table Task #2 ... Task node #2 NULL Task node #4 ... Task node #1 Task node #3 Task node #4 N O N - D I S C L O S U R E Task #8 Figure 4-6. Task link table The task link table contains one element per task configured in the system. The element contains a NULL-pointer if the task is in the suspended state, or the task node address if the task is in the nonsuspended state (it is saved there during task activation). For instance, in Figure 4-6 task#1 is not activated, while task#2 and task#8 are activated. Task#2 uses task node#4, and task#8 uses task node#1. The task configuration table contains the address of the task link element. The system uses this address when the task is referenced, and looks at the contents of the element of the task link table to define the current state of the task. If the OSEK OS supports task multiple activations, then the task link table contains one additional element per task. The element is the User's Manual 54 OSEK Operating System -- Rev 1.2 Task Management MOTOROLA 4.7.4.1 Stack Allocation During run-time, every task has its own stack. The stack is either dynamically assigned to a task during its activation or statically allocated for a task during system initialization. If a stack is allocated dynamically, it is got from a stack pool. Several options are possible for static stack assignment during system start-up. Stack pools are used by task management to dynamically allocate stack area for a task during task activation. To have stack pools in the system the configuration option StackPool must be turned on. The user should specify the desired number of stack pool with a defined number of buffers of the required size in them. This is done with the help of the STACK definition statements, see Section 12 System Configurationand Section 14 Building of Application. The stack pool contains a queue of stacks of a fixed size. The task control block contains the address of the stack pool control block, and the stack buffer is unlinked from the pool and assigned to the task during task activation. During task termination the stack buffer is returned to the stack pool. The simplest method of stack allocation is to use task node stacks. Each task in the OSEK Operating system has the stack linked with a task node. The size of this stack is the same for all tasks. It is defined by means of the corresponding OS property NodeStackSize. See Section 4.7.5 Allocation of Fixed Stack Linked with the Task Node for this option. The following options are available for task stack allocation: 1. Allocation of fixed stack linked with the task node. 2. Dynamic stack allocation from the stack pool. 3. Persistent stack allocation from the stack pool. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Task Management 55 A G R E E M E N T 4.7.4 Task Stack N O N - D I S C L O S U R E counter of times of activation. That is, the content of this field increments each time the task to be activated is in the non-suspended state, and decrements each time the task is terminating. R E Q U I R E D Task Management Task Related Resources 4. Explicit stack allocation. These options may be used simultaneously in the system, but each task must use only one of them. These options allow the user to optimize stack usage in the application. The use of the stack allocation options is illustrated in Figure 4-7, Figure 4-8, Figure 4-9, Figure 4-10 and explained below. 4.7.5 Allocation of Fixed Stack Linked with the Task Node Task configuration table #1 Task node #1 Task node stack stack pointer task node stack Figure 4-7. Fixed stack linked with the task node To allocate a task stack in this manner, the NODESTACK value should be assigned to the StackMethod task property. Every task control block in the system has an associated stack. The size of this stack is defined by means of the NodeStackSize OS property and is the same for all task nodes. During task activation, the system allocates a task control block and the linked stack, and uses this stack as a task stack. Because all task control blocks have an associated stack, it is the simplest method of stack allocation. But, in this case, all tasks will use a stack of the same (fixed) size regardless of the stack space really needed for tasks. To remove such a stack type, the system configuration option NodeStack should be turned off. N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Task Management User's Manual 56 OSEK Operating System -- Rev 1.2 Task Management MOTOROLA Task configuration table #2 stack pool node Stack pool Task node #2 Stack buffer stack buffer stack pointer Figure 4-8. Dynamic stack allocation from the stack pool To force a task to use dynamic stack allocation, the POOLSTACK value should be assigned to the StackMethod task property and the reference to the stack pool. The stack pool is defined separately and it is statically assigned to the task. Task #2 is configured to allocate a stack from the stack pool during task activation. The task configuration table contains the address of the stack pool, and the system allocates a stack buffer from this pool, saving the address of the stack buffer in task node #2. During task termination the stack buffer is returned to the stack pool queue. The user is allowed to configure a stack pool of different sizes and set the number of stack buffers in each to satisfy different stack space requirements for various tasks. NOTE: The user is responsible for the proper quantity of stack buffers to avoid a possible failure of task activation if there are no stack buffers left. Also, the increased time of task activation/termination due to stack pool manipulations timing should be taken into consideration. This method allows most efficient RAM distribution for task stacks. 4.7.5.2 Persistent Stack Allocation from the Stack Pool To use persistent stack allocation from the stack pool the user should set both PersistentNode and PersistentStack task properties. The system configuration option PersistentStack must be turned on. In this case, the task stack is allocated from the stack pool during system initialization and the address of the stack is written in the task control block, which is OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Task Management 57 N O N - D I S C L O S U R E 4.7.5.1 Dynamic Stack Allocation from the Stack Pool A G R E E M E N T R E Q U I R E D Task Management Task Related Resources R E Q U I R E D Task Management persistently designated to the task too. In Figure 4-9 task #3 is configured so that the persistent task node and a stack buffer from the specified pool are allocated for the task at system start-up, and the address of the allocated stack buffer is placed in the task node. Task configuration table #3 A G R E E M E N T stack pool node task node address Stack pool Buffer Buffer Buffer Persistent buffer Task nodes Free task node #1 Buffer Task node #3 stack buffer stack pointer Free task node #2 Persistent task node #3 N O N - D I S C L O S U R E Free task node #4 Figure 4-9. Persistent stack allocation from the stack pool NOTE: Persistent stack from a stack pool may be assigned only for the task with assigned persistent task node and with assigned stack pool. User's Manual 58 OSEK Operating System -- Rev 1.2 Task Management MOTOROLA Task configuration table #4 Static stack Task node #4 stack pointer top of stack Figure 4-10. Static stack allocation Persistent stack allocation is selected when the OWNSTACK value is given to the StackMethod property in the task definition. The system configuration option TaskOwnStack must be turned on. The user must also specify the stack size. In the figure above, task #4 has a stack permanently assigned to the task. The user is allowed to assign one static stack area to different tasks, if these tasks are not activated simultaneously. But with such stack allocation there is the overhead connected with non-used RAM areas when the task is not activated. 4.7.5.4 Stack Size The minimal size of the task stack depends on: * the scheduling policy (non-preemptive or preemptive task); * the services that are used by the task; * the interrupt and error handling policy; * the processor type. The recommended values of the minimal task stack size are provided in Section 15.5 Task Stack Size. NOTE: If the task stack is less than the minimal value for the given configuration, it may lead to unpredictable behavior of the task and to a system crash. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Task Management 59 N O N - D I S C L O S U R E 4.7.5.3 Explicit Stack Allocation A G R E E M E N T R E Q U I R E D Task Management Task Related Resources 4.8 Programming Issues 4.8.1 Configuration Options The following system configuration options affect the task management: N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Task Management * MultiplyActivation The option controls the multiply activation ability for Conformance Classes. If the option is turned off, multiply activation is disabled for tasks of these Conformance Classes. This option may be turned on only for BCC2, ECC2 Conformance Classes. * TaskIndexMethod If this option is turned on then the intermediate vector of the pointers to the tasks control blocks is used (fast and deterministic access to task control blocks). * NodeStack This option defines the presence of task node stacks in the system. If it is turned off there are no task node stacks implemented. * StackPool This option defines the presence of stack pools in the system. If it is turned off, there are no stack pools implemented. * PersistentNode If this option is turned on, a persistent task control block may be assigned to the task. * PersistentStack If this option is turned on, a persistent stack buffer may be assigned to the task. * TaskOwnStack This option defines that a task may have its own stack. * UseSameContext If this option is turned on, the same run time context frame is used both for nonpreemptive and preemptive tasks in mixed-preemptive systems. User's Manual 60 OSEK Operating System -- Rev 1.2 Task Management MOTOROLA A G R E E M E N T If this option is turned on, the task control blocks are placed into the base page memory. It increases the system performance, since the CPU accesses the base page faster than extended memory. In this case, the user is responsible for the necessary amount of RAM in the base page for the desired number of task control blocks. 4.8.2 Data Types The OSEK OS establishes the following data types for the task management: * TaskType The abstract data type for task identification; * TaskRefType The data type to refer variables of the TaskType data type; * TaskStateType The data type for variables to store the state of a task; * TaskStateRefType The data type to refer variables of the TaskStateType data type. The following data types belong to OSEK OS extension: * TaskControlBlockType The data type for task control block (task node); * TaskControlBlockRefType The data type to refer variables of the TaskControlBlockType data type. Only these data types may be used for operations with tasks. 4.8.3 Task Definition Each task in an application is generated by means of using the TASK system generation statement. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Task Management 61 N O N - D I S C L O S U R E TaskBasePage * R E Q U I R E D Task Management Programming Issues The task definition looks like the following: TASK <TaskName> { TYPE = <TaskType>; PRIORITY = <TaskPriority>; SCHEDULE = <TaskScheduling>; ACTIVATION = <TaskMultiplyActivation>; AUTOSTART = <TaskInitState>; StackMethod = <TaskStackAssignment>; }; The application definition file contains one such statement per task. The task generation statement is described in detail in Section 12 System Configuration. To refer to a task, the constructional statement DeclareTask should be used to declare the task before references to it. DeclareTask looks like the following: DeclareTask( TaskType <TaskName> ) 4.8.4 Run-time Services OSEK OS grants a set of services for the user to manage tasks. A detailed description of these services is provided in Section 17 System Services. Here only a brief list of them is given. N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Task Management Table 4-4. Task Management Run-time Services Service Name ActivateTask TerminateTask Description Activates the task, i.e. put it from the suspended into the ready state Terminates the task, i.e. put it from the ready into the suspended state ChainTask Terminates the task and activates a new one immediately Schedule Yields control to a higher-priority ready task (if any exists) GetTaskId Gets the identifier of the running task GetTaskState Gets the status of the specified task GetTCBInfo(1) Copies contents of the running task control block by the address specified 1. This service is not defined in the OSEK OS v.2.0 rev.1 specification. This is an extension of OSEK OS. User's Manual 62 OSEK Operating System -- Rev 1.2 Task Management MOTOROLA The following constants are used within the OSEK Operating System to indicate task states: * RUNNING Constant of data type TaskStateType for task state running * WAITING Constant of data type TaskStateType for task state waiting * READY Constant of data type TaskStateType for task state ready * SUSPENDED Constant of data type TaskStateType for task state suspended These constants can be used for variables of the TaskStateType. The following constant is used within the OSEK OS to indicate task: * INVALID_TASK Constant of data type Task Type for an undefined task 4.8.6 Conventions Within the OSEK OS application a task should be defined according to the following pattern: TASK ( TaskName ) { ... } The name of the task function will be generated from TaskName by macro TASK. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Task Management 63 A G R E E M E N T 4.8.5 Constants N O N - D I S C L O S U R E Examples of using the run-time services are provided in Section 17.3.12 Examples for Task Management Services. R E Q U I R E D Task Management Programming Issues N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Task Management User's Manual 64 OSEK Operating System -- Rev 1.2 Task Management MOTOROLA 5.2 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 5.3 Scheduling Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 5.4 Programming Issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 5.2 General The algorithm deciding which task has to be started and triggering all necessary OSEK Operating System internal activities is called scheduler. It performs all actions to switch the CPU from one instruction thread to another. It is either switching from task to task or from ISR back to a task. The task execution sequence is controlled on the base of task priorities (see section Section 4.6 Task Priorities) and the scheduling policy used. The scheduler is activated whenever a task switch is possible according to the scheduling policy. The principle of multitasking allows the operating system to execute various tasks concurrently. The sequence of their execution depends on the scheduling policy, therefore it has to be clearly defined. Scheduler also provides the endless idle loop if there is no task ready to be running. It may occur, when all tasks are in the suspended or waiting state until the awakening signal from an Interrupt Service Routine occurs. In this case there is no currently running task in the system, and the scheduler occupies the processor performing an endless loop while the ISR awaits a task to be executed. It is possible to call a special user's hook from the scheduler idle loop. This property is turned on via the system configuration option IdleLoopHook. If it is supported by hardware, the scheduler's idle loop may be replaced by an instruction OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Scheduler 65 R E Q U I R E D 5.1 Contents A G R E E M E N T Section 5. Scheduler N O N - D I S C L O S U R E User's Manual -- OSEK Operating System that puts the CPU in low power mode to reduce power consumption. This property is turned on via the system configuration option HCLowPower. The scheduler has its own small stack (the scheduler's stack) which is needed for the endless idle loop. The stack size is specified by the user, see section Section 13.3.1 Global System Attributes. The system property UseMainStack can be specified by the user. In this case, the same stack is used by the main() function, by the scheduler and by ISRs. This option saves RAM consumption, but the user is responsible for the required memory amount for the stack. The scheduler can be treated as a specific resource that can be occupied by any task. See Section 7.3.2 Scheduler as a Resource for details. The scheduling policy and some scheduler-related parameters are defined by the user, see Section 13.3.1 Global System Attributes and Section 13.3.2 Task Related Attributes. 5.2.1 Simple Scheduler If each task in the application has an unique priority, the simplified scheduler may be used to reduce memory and time consumption. In this case, the scheduler uses a table of tasks instead of queues. This system property can be turned on via the system configuration option SimpleScheduler. By default this option is turned off. N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Scheduler The option does not depend on Conformance Classes so it is possible to use this system property in ECC2 as well as in BCC1, but unique task priorities are required (one task per priority). The simplified scheduler cannot be used with resource management and task multiply activation. Therefore, if the SimpleScheduler and the Resources or MultiplyActivation options are both turned ON in the system configuration file, then SimpleScheduler is ignored by the System Generator, and an error message is produced (see Section 12 System Configuration). User's Manual 66 OSEK Operating System -- Rev 1.2 Scheduler MOTOROLA Note that the interruptibility of the system depends neither on the Conformance Class, nor on the task type. The desired scheduling policy is defined by the user via the system configuration option SCHEDULE. The valid values are - NON, FULL, MIXED. 5.3.1 Non-preemptive Scheduling The scheduling policy is considered as non-preemptive, if a task switch is only performed via one of a selection of explicitly defined system services (explicit point of rescheduling). Non-preemptive scheduling imposes particular constraints on the possible timing requirements of tasks. Specifically, the lower priority non-preemptive section of a running task delays the start of a task with higher priority, up to the next point of rescheduling. The time diagram of the task execution sequence for this policy looks like the following: OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Scheduler 67 A G R E E M E N T The scheduling policy being used determines whether execution of a task may be interrupted by other tasks or not. In this context, a distinction is made between full-, non- and mixed-preemptive scheduling policies. The scheduling policy affects the system performance and memory resources. In the OSEK Operating System, all listed scheduling policies are supported, but in the case of the mixed-preemptive policy, each task in an application may use only one of the three policies. It is defined via the appropriate task property (preemptive/non-preemptive). N O N - D I S C L O S U R E 5.3 Scheduling Policy R E Q U I R E D Scheduler Scheduling Policy R E Q U I R E D Scheduler latency time activation of task T1 for task T1 suspended Task T2 running ready running suspended terminaton of task T2 A G R E E M E N T N O N - D I S C L O S U R E Task T1 Figure 5-1. Non-preemptive scheduling Task T2 has lower priority than task T1. Therefore, it delays task T1 up the point of rescheduling (in this case termination of task T2). The following points of rescheduling exist in the OSEK Operating System: * Successful termination of a task (via the TerminateTask system service); * Successful termination of a task with explicit activation of a successor task (via the ChainTask system service); * Explicit call of the scheduler (via the Schedule system service); * Explicit wait call, if a transition into the waiting state takes place (via the WaitEvent system service, Extended Tasks only). In the non-preemptive system, all tasks are non-preemptive and the task switching will take place exactly in the listed cases. 5.3.2 Full-preemptive Scheduling Full-preemptive scheduling means that a task which is presently running may be rescheduled at any instruction by the occurrence of trigger conditions preset by the operating system. Full-preemptive scheduling will put the running task into the ready state as soon as a higher-priority task has got ready. The task context is saved so that the preempted task can be continued at the location where it was interrupted. User's Manual 68 OSEK Operating System -- Rev 1.2 Scheduler MOTOROLA With full-preemptive scheduling, the latency time is independent of the run time of lower priority tasks. Certain restrictions are related to the increased RAM space required for saving the context, and the enhanced complexity of features necessary for synchronization between tasks. As each task can theoretically be rescheduled at any location, access to data that are used jointly with other tasks must be synchronized. terminaton of task T1 Task T1 suspended running suspended Task T2 running ready running terminaton of task T2 Figure 5-2. Full-preemptive scheduling 5.3.3 Mixed-preemptive Scheduling If full-preemptive and non-preemptive scheduling principles are to be used for execution of different tasks on the same system, the resulting policy is called "mixed-preemptive" scheduling. The distinction is made via the task property (preemptive/non-preemptive). The definition of a non-preemptive task makes sense in a full-preemptive operating system in the following cases: * if the execution time of the task is in the same magnitude of the time of a task switch, * if RAM is to be used economically to provide space for saving the task context, * if the task must not be preempted. Many applications comprise only a few parallel tasks with a long execution time, for which a full-preemptive operating system would be convenient, and many short tasks with a defined execution time where OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Scheduler 69 N O N - D I S C L O S U R E activation of task T1 A G R E E M E N T In a full-preemptive system all tasks are preemptive. R E Q U I R E D Scheduler Scheduling Policy non-preemptive scheduling would be more efficient. For this configuration, the mixed-preemptive scheduling policy was developed as a compromise. NOTE: Tasks can be ported between preemptive, non-preemptive and mixedpreemptive OSEK applications if they do not have any assumption of non-preemptability. That means that critical data must be protected using resources and communication must be done using messages. 5.4 Programming Issues 5.4.1 Configuration Options The following system configuration options are intended to define scheduler properties: N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Scheduler * SimpleScheduler If this option is turned on, the simplified scheduler will be used in the system if each task has a unique priority. It reduces the OS code and increases system performance. * SCHEDULE This option defines which scheduling policy, non-preemptive, full-preemptive or mixedpreemptive, will be used in the application. * UseMainStack If this option is turned on, the same stack area is used for the main() function (during start-up), for the scheduler stack and for the ISR stack. * IdleLoopHook If this option is turned on, then user supplied hook will be called from the scheduler idle loop. * HCLowPower If this option is turned on, an instruction that puts the CPU in low power mode is used instead of the scheduler's idle loop. User's Manual 70 OSEK Operating System -- Rev 1.2 Scheduler MOTOROLA The scheduler can be used by the programmer as a resource (in all Conformance Classes). To provide this possibility, the services GetResource and ReleaseResource with the constant RES_SCHEDULER as a parameter can be called by a task. It means that the task cannot be preempted by any other task after the scheduler occupation, before the corresponding call ReleaseScheduler is performed. While the task occupies the scheduler, it has the highest priority and, therefore, cannot be interrupted by other tasks (only ISRs can get the CPU control during this period). Such programming practice can be used for important critical sections of code. See the example: GetResource( RES_SCHEDULER ); ... /* Critical section - this code cannot be interrupted by any other task */ ... ReleaseResource( RES_SCHEDULER ); /* End of the critical section */ 5.4.3 Scheduler Definition The scheduler parameters must be defined by the user in the configuration file by setting the corresponding OS attributes. Definition of scheduler related system properties looks like the following: OS <name> { ..... SCHEDULE = MIXED; NodeNumber = <NumberOfTasks>; SchedStackSize = <SchedulerStackSize>; MaxPrio = <NumberOfPriorities>; NodeStackSize = <TaskNodeStackSize>; ..... }; The OS generation statement is described in detail in Section 12 System Configuration. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Scheduler 71 A G R E E M E N T The scheduler is not accessed by the user directly. The user can only pass the CPU control to the scheduler by means of the Schedule system service. This leads to task rescheduling. N O N - D I S C L O S U R E 5.4.2 Run-time Services R E Q U I R E D Scheduler Programming Issues N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Scheduler User's Manual 72 OSEK Operating System -- Rev 1.2 Scheduler MOTOROLA 6.2 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 6.3 ISR Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 6.4 ISR Categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 6.5 Interrupt Flag Manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 6.6 Local Variables Considerations . . . . . . . . . . . . . . . . . . . . . . . . 78 6.7 Programming Issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 6.2 General Interrupt processing is an important part of any real-time operating system. An Interrupt Service Routine (ISR) is a routine which is invoked from an interrupt source, such as a timer or an external hardware event. ISRs have higher priority than all tasks and the scheduler. Addresses of ISRs should be pointed to in the vector table. In OSEK OS, all ISRs should use the separate stack (ISR stack) which is used only by ISRs during their execution. The size of the ISR stack is defined by the user. At the beginning of an Interrupt Service Routine, the user should switch to this stack using the system service EnterISR. After the ISR completion, the corresponding service LeaveISR should be performed to switch back to the previous stack. The instruction sequence between the EnterISR and LeaveISR calls is considered as ISR frame. When interrupt occurs, either current stack can be used or the ISR stack. The current stack is: * the stack of the interrupted task, OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Interrupt Processing 73 R E Q U I R E D 6.1 Contents A G R E E M E N T Section 6. Interrupt Processing N O N - D I S C L O S U R E User's Manual -- OSEK Operating System R E Q U I R E D Interrupt Processing * the scheduler's stack if an interrupt occurred during scheduler execution, * ISR stack in case of nested interrupts. A G R E E M E N T OSEK OS supports nested interrupts, theoretically up to 255 levels1. A special system counter tracks the number of nested interrupts. Since the OS provides the means to switch the stack and to control the interrupt mask, such nested interrupts, if written correctly, could be treated as a single one. To not waste a task stack space for nested interrupts or complicated ISR, the ISR stack is used. OS also controls the state of an interrupt mask. The user defines values of the interrupt masks for disabling and enabling all interrupts, and the default interrupt mask for task execution. See Section 13.3.3 Interrupt Related Properties for details. N O N - D I S C L O S U R E ISRs can communicate with tasks in the OSEK OS by the following means: * ISR can activate a task; * ISR can send an unqueued or a queued message to a task; * ISR can trigger a counter; * ISR can get state of the task; * ISR can set event for a task; * ISR can get event mask of the task; * ISR can manipulate alarms; * ISR can get active application mode. Interrupts cannot use any OS services except those which are specially allowed to be used within ISRs. When using other services, the system behavior will be unpredictable. In the Extended (debugging) status of the Operating System, the error will be reported in such a case. See 1. If PreTaskHook/PostTaskHook user's hooks are used (see Section 11.3 Hook Routines) and GetTaskId directive is supported (see Section 17.3.9 GetTaskId) then OSEK OS supports up to 127 levels of nested interrupts. User's Manual 74 OSEK Operating System -- Rev 1.2 Interrupt Processing MOTOROLA The purpose of the ISR stack is to save memory. Since interrupts can be nested, it means, that every task stack must be big enough to store several interrupt stack frames (in addition to task needs for local variables, function calls, etc.). To avoid this overhead, the separate ISR stack is used in the OSEK Operating System. Switching to this stack is performed by the EnterISR service at the beginning of ISR. This stack is used only by ISRs, and if nested interrupts occur after the stack has been switched, they will use this stack too. Before leaving the ISR, switching back to the interrupted task stack must be achieved by means of LeaveISR. The interrupt stack frame usually consists of the CPU registers, and optionally some compiler-dependent `virtual' registers. The CPU registers are pushed onto the stack under hardware or software control. In the latter case the compiler generates a stack frame by means of adding special sequences of machine instructions before the first statement in the function. Most compilers use function modifiers (like `interrupt') to generate stack frames. In turn, the ISR keyword, specified in OSEK (see Section 6.7.4 Conventions), is a macro for this modifier. 6.4 ISR Categories In the OSEK Operating System three types of Interrupt Service Routines are considered. 6.4.1 ISR Category 1 ISRs of this type do not use any operating system service. These ISRs do not use OS services EnterISR and LeaveISR, consequently, ISRs of these type are executed on the current stack. In this case, if the ISR uses OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Interrupt Processing 75 A G R E E M E N T 6.3 ISR Stack N O N - D I S C L O S U R E Section 6-1 Interrupt Management Services in the OSEK OS and Section 17 System Services for details. R E Q U I R E D Interrupt Processing ISR Stack the stack space for its execution, the user is responsible for the appropriate stack size. Moreover, if interrupts are re-enabled inside the ISR, nested interrupts are possible, which will use the same task stack. The general recommendation for ISRs category 1 may be the following: RULE: ISR category 1 cannot use any OS services. These ISRs must disable interrupts internally (at the beginning of the routine). After the ISR is finished, processing continues exactly at the instruction where the interrupt occurred, i.e. the interrupt has no influence on task management. ISR( ISR_handler ) { ... /* the code without any OS service calls */ ... } 6.4.2 ISR Category 2 In ISR category 2, the OSEK Operating System provides an automatic EnterISR call at the very beginning to switch to the ISR stack and save the initial interrupt mask. After that, any user's routine can be executed, including allowed OS calls (to activate a task, send a message or trigger a counter). See Section 6.7.3 Run-time Services for the list of services allowed for ISR. At the end of the ISR, the System automatically executes LeaveISR service to switch back to the task stack and restore the interrupt mask. N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Interrupt Processing ISR( ISR_handler ) { /* OS internal EnterISR() call */ ... /* the code with allowed OS calls */ ... /* OS internal LeaveISR() call */ } Inside the ISR, no rescheduling will take place. Rescheduling may only take place on termination of the ISR if a preemptive task has been interrupted. User's Manual 76 OSEK Operating System -- Rev 1.2 Interrupt Processing MOTOROLA ISR( ISR_handler ) { /* user's code */ ... EnterISR(); /* the code with allowed OS calls */ ... LeaveISR(); } To avoid possible errors the following rule for ISR category 3 is recommended: RULE: In ISR category 3, all operations using OS services and/or with enabled interrupts must be performed only inside the ISR frame. The OSEK Operating System has no means to distinguish ISR categories 2 and 3 at run-time. Therefore, such distinction should be made by the user at the stage of source code writing. 6.5 Interrupt Flag Manipulation OSEK OS provides services to control the interrupt flag - to disable or enable interrupts and get the current state of the interrupt mask. These services are implemented to allow the user to control interrupts of several interrupt levels (for instance, Motorola MC68HC16 MCU has 8 interrupt levels). In this case, it is possible to set the desired interrupt OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Interrupt Processing 77 A G R E E M E N T In ISR category 3, the OSEK Operating System provides the ISR frame to execute more complicated user code. The ISR frame is instructions between OS services EnterISR and LeaveISR. Such ISRs are similar to those of category 2, but the location of the ISR frame in the code segment is application dependent and user defined. The code outside the ISR frame can be used, e.g., to access global variables or hardware registers. The user is responsible for operations outside the ISR frame, since they could unproperly modify stack frame (see Section 6.6 Local Variables Considerations), and interrupts may be enabled (see Section 6.4.1 ISR Category 1). No OS service calls can be executed outside the ISR frame. N O N - D I S C L O S U R E 6.4.3 ISR Category 3 R E Q U I R E D Interrupt Processing Interrupt Flag Manipulation mask which disables some interrupts and enables other ones. In the interrupt definition statement, the user should select interrupt masks for all interrupts disabled, all interrupts enabled and some desired medium state (by default a task gets this interrupt mask when it is activated if it does not have its own starting interrupt mask specified). The special data type is defined within the OSEK Operating System to control interrupt masks. The set of special OS attributes is introduced to configure interrupt masks. 6.6 Local Variables Considerations There are some peculiarities related to using local variables inside ISR category 3. The following considerations cover this subject. The EnterISR and LeaveISR functions assume that the stack frame is defined on entry. Moreover, the stack pointer may be changed during the execution of these functions. Thus, the use of local variables inside ISR category 3 may lead to unpredictable behavior and a crash. Therefore, the user is not permitted to use local variables inside ISR category 3. Instead, the user may split the interrupt service routine into two functions. The nested function should perform useful work, and may have local variables. The outermost function should call the nested function framed by the calls to EnterISR and LeaveISR services. N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Interrupt Processing The example of correct code: int __SciHandler(void) { char status; int num; ... } /* The inner function with local variables */ /* local variable to hold SCI status*/ /* local variable to byte counter*/ /* useful user's code*/ ISR( SciHandler ) { EnterISR(); __SciHandler(); LeaveISR(); } /* /* /* /* Interrupt service routine*/ No local variables defined*/ Switch to the ISR stack */ Perform useful work to handle interrupt*/ User's Manual 78 OSEK Operating System -- Rev 1.2 Interrupt Processing MOTOROLA The example of the wrong code - local variables are allocated on the task stack, but the stack pointer is changed by EnterISR after, therefore references to the variables are invalid: int __SciHandler(void) { /* The inner function without local variables */ ... /* useful user's code*/ } 6.7 Programming Issues 6.7.1 Configuration Options The following system configuration options affect the interrupt management: * EntryExitISR * InterruptMaskControl if the option is turned off, it is assumed that there are no interrupts in the system at all and the Operating System does not have any interrupt handling mechanisms. No interrupt management services are implemented. if the option is turned off (while the EntryExitISR option is turned on), interrupt masks are not controlled by the operating system. Services EnableInterrupt, DisableInterrupt, GetInterruptDescriptor are not implemented. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Interrupt Processing 79 N O N - D I S C L O S U R E A G R E E M E N T ISR( SciHandler ) /* Interrupt service routine*/ { char status; /* local variable to hold SCI status*/ int num; /* local variable to byte counter*/ EnterISR(); /* Stack Pointer is changed ! */ num = __SciHandler();/* Perform useful work to handle interrupt*/ LeaveISR(); } R E Q U I R E D Interrupt Processing Programming Issues N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Interrupt Processing * ISRCategory1 if the option is turned off, it is assumed that there are no interrupts of category 1 in the system. * ISRCategory2 if the option is turned off, it is assumed that there are no interrupts of category 2 in the system. * ISRCategory3 if the option is turned off, it is assumed that there are no interrupts of category 3 in the system. * UnorderedExceptions if the option is turned on, it is possible to handle unordered exceptions. This attribute is intended for MPC only. 6.7.2 Data Types The OSEK OS establishes the following data types for the task management: * IntDescriptorType The data type for logical interrupt descriptors; * IntDescriptorRefType The data type to refer variables of the IntDescriptorType data type. The only data types must be used for operations with interrupt masks. 6.7.3 Run-time Services OSEK OS provides the set of services for interrupt management. Also some services may be used both on the task level and on the ISR level. These services are shown in the Section 6-1 Interrupt Management Services in the OSEK OS. User's Manual 80 OSEK Operating System -- Rev 1.2 Interrupt Processing MOTOROLA R E Q U I R E D Interrupt Processing Programming Issues Table 6-1. Interrupt Management Services in the OSEK OS Description EnterISR Registers the switching to the interrupt level and switch context to the ISR stack LeaveISR Registers the leaving of the ISR level EnableInterrupt Enables interrupts in accordance with the given logical interrupt descriptor DisableInterrupt Disables interrupts in accordance with the given logical interrupt descriptor GetInterruptDescriptor Returns the current state of interrupts A G R E E M E N T Interrupt Management Services Services allowed for use in ISR ActivateTask Activates the specified task (puts it into the ready state) GetTaskState Gets state of the task SetEvent Sets event for the task GetEvent Gets event of the task SendMessage Sends an unqueued message in WithCopy configuration to the specified task ReceiveMessage Delivers data of an unqueued message in WithCopy configuration to the application message copy GetMessageStatus Returns the current status of the message GetAlarmBase Gets alarm base characteristics SetRelAlarm Sets relative alarm SetAbsAlarm Sets absolute alarm CancelAlarm Cancels alarm GetAlarm Gets value in ticks before the alarm expires CounterTrigger Increments a counter value GetActiveApplicationMode Gets current application mode 6.7.4 Conventions Within the application, an Interrupt Service Routine category should be defined according to the following pattern: ISR( ISRName ) { ... OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Interrupt Processing 81 N O N - D I S C L O S U R E Service Name } The keyword ISR is the macro for compiler specific interrupt function modifier, which is used to generate valid code to enter and exit ISR. If the Interrupt Service Routine is defined by means of keyword ISR usage, then it should be declared according to the following pattern: DeclareISR( ISRName ) The same name shall be used for corresponding ISR object definition (see Section 13.11 ISR Definition). 6.7.5 ISR Definition To define common ISR parameters like ISR stack size and predefined interrupt masks the corresponding OS properties should be specified in the configuration file. Definition of Interrupt related properties looks like: OS <name> { ..... IsrStackSize = <ISRStackSize>; DisableInterruptMask = <DisableMask>; EnableInterruptMask = <EnableMask>; InitialMask = <InitialMask>; TaskLevelMask = <TaskMask>; ..... }; N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Interrupt Processing Definition of specific ISR object looks like: ISR <ISRName>{ ..... CATEGORY = 2; ..... }; See Section 13.3.3 Interrupt Related Properties and Section 13.11 ISR Definition for the details. User's Manual 82 OSEK Operating System -- Rev 1.2 Interrupt Processing MOTOROLA 6.7.6 Constants For initial interrupt mask the special constant is provided by the operating system: INITIAL_INTERRUPT_DESCRIPTOR - the interrupt level to be used during system startup, after user's StartupHook and before the first user task is running (see Section 11.5 Start-up Routine). It is the same as InitialMask value. N O N - D I S C L O S U R E A G R E E M E N T * R E Q U I R E D Interrupt Processing Programming Issues OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Interrupt Processing 83 N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Interrupt Processing User's Manual 84 OSEK Operating System -- Rev 1.2 Interrupt Processing MOTOROLA 7.2 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 7.3 Access to Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 7.4 Programming Issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 7.2 General The resource management is used to coordinate concurrent accesses of several tasks to shared resources, e.g. management entities (scheduler), program sequences (critical sections), memory or hardware areas. In general, the resource management is provided in all Conformance Classes, but it is fully supported only beginning from the BCC2 Conformance Class. In the lower Conformance Classes only the scheduler is treated as the specific system resource which can be used by tasks. Resource management ensures that * two tasks cannot occupy the same resource at the same time, * priority inversion cannot arise while resources are used, * deadlocks do not occur by use of these resources, * access to resources never results in a waiting state. The functionality of resource management is only required in the following cases: * full-preemptive tasks, OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Resource Management 85 R E Q U I R E D 7.1 Contents A G R E E M E N T Section 7. Resource Management N O N - D I S C L O S U R E User's Manual -- OSEK Operating System R E Q U I R E D Resource Management * non-preemptive scheduling, if resources are also to remain occupied beyond a scheduling point (except the scheduler resource); * non-preemptive scheduling, if the user intends to have the application code executed under other scheduling policies too. A G R E E M E N T Resources cannot be occupied by more than one task at a time. The resource that is now occupied by a task must be released before other tasks can get it. The OSEK operating system ensures that tasks are only transferred from the ready state into the running state if all resources which might be occupied by that task during its execution have been released. Consequently, no situation occurs in which a task tries to access an occupied resource. The special mechanism is used by the OSEK Operating System to provide such behavior, see Section 7.3.1 Priority Ceiling Protocol for details. The waiting state is not admissible for Extended Tasks while a resource is occupied. It means that the task occupying a resource is not allowed to call the WaitEvent service. N O N - D I S C L O S U R E In case of multiple resource occupation, the task must request and release resources following the LIFO principle (stack). For example, if the task needs to get the communication hardware and then the scheduler to avoid possible preempts, the following code may be used: GetResource( SCI_res ); ... GetResource( RES_SCHEDULER ); ... ReleaseResource( RES_SCHEDULER ); ReleaseResource( SCI_res ); /* /* /* /* /* /* occupy the SCI resource */ user's code */ occupy the scheduler resource */ user's code */ release the scheduler */ release the SCI resource */ OSEK OS resource management allows the user to prevent such situations as priority inversion and deadlocks which are the typical problems of common synchronization mechanisms in real-time applications (e.g., semaphores). User's Manual 86 OSEK Operating System -- Rev 1.2 Resource Management MOTOROLA In the OSEK Operating System, resources are ranked by priority. Each resource is assigned statically to a user defined priority, which is called Ceiling Priority. It is possible to have resources with the same priorities, but the resource Ceiling Priority must be identical to or higher than the highest task priority with access to this resource. This resource feature supports the Priority Ceiling Protocol. 7.3.1 Priority Ceiling Protocol The Priority Ceiling Protocol is implemented in the OSEK Operating System as a resource management discipline. The priority ceiling protocol elevates the task requesting a resource to a priority level. This priority can simply be calculated during system generation. As shown in Section 7.2 General the Ceiling Priority is: * Identical to or higher than the highest task priority with access to this resource (task T1); * Lower than all other tasks of higher priority than task T1. When a task occupies a resource, the system temporarily changes its priority. It is automatically set to the Ceiling Priority by the resource management. Any other task which might occupy the same resource does not enter the running state due to its lower or equal priority. If the resource occupied by the task is released, the task returns to its former priority level. Other tasks which might occupy this resource can now enter the running state. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Resource Management 87 A G R E E M E N T Before they are used, resources must be defined by the user at the system configuration stage via the RESOURCE definition, see Section 13.6 Resource Definition. Then the resource is declared in the source file, where it will be used by means of a system declaration statement DeclareResource (see Section 17.5 Resource Management Services). After that, the task can occupy and release the resource using the GetResource and ReleaseResource services. While the resource is occupied, i.e., while the code between these services is executed, this resource cannot be requested by another task. N O N - D I S C L O S U R E 7.3 Access to Resources R E Q U I R E D Resource Management Access to Resources R E Q U I R E D Resource Management The example shown in Figure 7-1 illustrates the mechanism of the Priority Ceiling Protocol. Ceiling priority running release resource running suspended ready running suspended A G R E E M E N T N O N - D I S C L O S U R E release resource running ready suspended running ready running suspended running suspended ready request resource running request resource Figure 7-1. Priority Ceiling Protocol In the figure above, Task 1 has the highest priority and Task 4 has the lowest Priority. The resource has a priority greater than or equal to the Task 1 priority. When Task 4 occupies the resource, it gets a priority not less than Task 1, therefore it cannot be preempted by ready Task 1 until it releases the resource. Just after the resource is released, Task 4 is returned to its low priority and becomes ready, and Task 1 becomes the running task. When Task 1, in its turn, occupies the resource, its priority is also changed to the Ceiling Priority. 7.3.2 Scheduler as a Resource The OSEK operating system treats the scheduler as a specific resource which is accessible to all tasks. Therefore, a standard resource with the predefined identifier RES_SCHEDULER is generated, and it is supported in all Conformance Classes. If a task calls the services GetResource or ReleaseResource with this identifier as a parameter, the task will occupy or release the scheduler in the manner of a simple resource. See the code example in Section 7.2 General. User's Manual 88 OSEK Operating System -- Rev 1.2 Resource Management MOTOROLA If a non-preemptive task gets the scheduler as a resource it must release it before the point of rescheduling! NOTE: If task got the scheduler and tries to yield CPU via the Schedule service then Schedule service returns immediately without doing anything. 7.4 Programming Issues 7.4.1 Configuration Options The following system configuration options control the resource management in the OSEK OS: * Resources this option defines whether resource management is provided by the OS or not. * FastResource the option can be specified by the user to increase the system performance. If it is turned on, the system will work faster. But this option may be used only for debugged applications, because errors related to incorrect access and priority are not signalled. If this option is turned on, less ROM and RAM are needed for resources. But, if resource priorities have a large difference (e.g. first resource has priority 1 and the second resource has priority 20) this option does not lead to RAM saving. * ResourceAccessCheck the option defines whether E_OS_ACCESS error code is returned by GetResource service or not. If it is TRUE, then error code will be returned in EXTENDED status based on task definition in OIL-file. If the system has OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Resource Management 89 A G R E E M E N T NOTE: N O N - D I S C L O S U R E If a task wants to protect itself against preemptions by all other tasks, it can occupy the scheduler exclusively. When it is occupied, interrupts are received and processed normally. However, it prevents the rescheduling of tasks. R E Q U I R E D Resource Management Programming Issues N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Resource Management STANDARD status or FastResource option turned on or more than 8 resources (including Scheduler) are defined in application, then this option should be set to FALSE. 7.4.2 Data Types The OSEK OS establishes the following data type for the resource management: * ResourceType the abstract data type for referencing a resource; The only data type must be used for operations with resources. 7.4.3 Run-time Services OSEK OS grants a set of services for the user to manage resources. Detailed descriptions of these services are provided in Section 17.5 Resource Management Services. Here only a brief list of them is given. Service Name Description GetResource(1) This call serves to occupy the resource (critical section of the code, assigned to the resource) ReleaseResource Releases the resource assigned to the critical section (to leave the critical section) 1. E_OS_ACCESS error code is not returned by GetResource service if more than 8 resources (including RES_SCHEDULER) are defined in the application or FastResource configuration option is turned on or ResourceAccessCheck configuration option is turned off. 7.4.4 Resource Definition To define a resource, the following definition statement should be specified in the generation file: RESOURCE <ResourceID> { PRIORITY = <ResourcePriority>; }; User's Manual 90 OSEK Operating System -- Rev 1.2 Resource Management MOTOROLA R E Q U I R E D Resource Management Programming Issues For more details see Section 13.6 Resource Definition. To refer to a resource, the declaration statement DeclareResource should be used to declare the resource before its use. DeclareResource looks like the following: DeclareResource( ResourceType <ResourceID> ) N O N - D I S C L O S U R E A G R E E M E N T This declaration is equivalent to the external declaration of variables. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Resource Management 91 N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Resource Management User's Manual 92 OSEK Operating System -- Rev 1.2 Resource Management MOTOROLA 8.2 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 8.3 Counters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 8.4 Alarms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 8.5 Programming Issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 8.2 General The OSEK operating system comprises a two level concept to make use of recurring events like periodic interrupt of timers, interrupt of the sensors on rotating angles, or any recurring software events. To manage such a situation, counters and alarms are provided by the OSEK Operating System. The recurring events (sources) can be registered by counters. Based on counters, the OSEK OS offers an alarm mechanism to the application software. Counters and alarms are provided by the OSEK OS in all Conformance Classes. Counter concept and counter management system services are based in the `OSEK Operating System, Concept' v. 1.00, September 1995 and `OSEK Operating System, Application Program Interface' v. 1.00, September 1995. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Counters and Alarms 93 R E Q U I R E D 8.1 Contents A G R E E M E N T Section 8. Counters and Alarms N O N - D I S C L O S U R E User's Manual -- OSEK Operating System source source 1:1 alarm source source n:1 counter counter alarm alarm ActivateTask Task alarm 1:n counter counter alarm alarm SetEvent Task Figure 8-1. Counters and alarms 8.3 Counters Any event in the system can be linked with a counter, so that when the event has occurred, the counter value is changed. A counter is identified in the system via its symbolic name, which is assigned to the counter statically at the configuration stage. A counter is represented by a current counter value and some counter specific parameters: counter initial value, conversion constant and maximum allowed counter value. They are defined by the user. The latter two parameters are constants and they are defined at system generation time. The counter initial value is the dynamic parameter. The user can initialize the counter with this value and thereafter on task or on interrupt level advance it using the system service CounterTrigger. N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Counters and Alarms The maximum allowed counter value specifies the number after which the counter rolls over. When a counter reaches its maximum allowed possible value (or rolls over the predefined size - byte etc.), it starts counting again from zero. NOTE: The maximum allowed counter value is never really reached by a counter. It means that if, for instance, value 5 is specified as the maximum allowed one, 5 can never be read as a current counter value. User's Manual 94 OSEK Operating System -- Rev 1.2 Counters and Alarms MOTOROLA The conversion constant can be used to convert the counter value into an appropriate user specific unit of measurement, e.g. seconds for timers, angular degrees for rotating axles. The conversion is done by the user's code and this parameter can be treated as a counter-specific reference value. The operating system provides the standard service GetCounterInfo to read these counter specific values. Also the service GetCounterValue is designed to read the current counter value. At least one counter always exists in the system. This counter is used as a system timer (the internal system clock). The system timer is a standard counter with the following additions: * the user must always define the system timer in an application; * special constants are defined to describe counter parameters and to decrease access time; * the user defines the source of hardware interrupts for the system counter. In the system definition statement for the system timer the user should define one of possible hardware interrupt sources. Parameters to tune the hardware can be also defined by the user in this statement. This possibility allows the user to exactly tune the system (see SECTION 15 Platform-Specific Features for details). If hardware related parameters are defined, the code to initialize the system timer hardware and the interrupt handler are automatically provided for the user as a part of OSEK OS. In that case the user does not have to care about handling of this interrupt and he/she can not change the provided code. If the parameters are not defined the user has to provide the code to initialize the hardware and handle the OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Counters and Alarms 95 A G R E E M E N T The user also defines the maximal size of all counters in the system they can be byte-, word- or longword-sized. This is defined via the system properties CounterSize. N O N - D I S C L O S U R E If an alarm should be set for value 5, the maximum allowed counter value must be 6. R E Q U I R E D Counters and Alarms Counters R E Q U I R E D Counters and Alarms interrupt. In this case in ISR for the specified interrupt the service CounterTrigger must be used to advance the counter. NOTE: The system timer has a predefined conversion constant that equals to the number of ticks required to reach 10 milliseconds. Hardware interrupts which are used to trigger counters have to be handled in usual manner. To perform any actions with the counter the application software processing the event should call the system service CounterTrigger. This service must be called within the ISR frame created by the EnterISR and LeaveISR services. It is not allowed to use CounterTrigger in ISR category 1 (see section Section 6.4 ISR Categories). A G R E E M E N T N O N - D I S C L O S U R E The system timer will not be triggered if the EntryExitISR property is turned OFF! The user is free to assign one source exactly to one counter (1:1 relationship), several sources to one counter (n:1 relationship), or one source to several counters (1:n relationship), see Figure 8-1. Meaning that it is possible to advance the same counter in different software routines. User can alternatively increment the value of a counter using AdvanceCounter service. This service advances the current value of the counter by the number of ticks specified (CounterTrigger increments counter by 1). If alarms are linked to the counter, the system checks whether they expired during a specified number of ticks and performs appropriate actions (task activation and event setting). NOTE: AdvanceCounter service is not allowed to be used in ISR. NOTE: AdvanceCounter service is not defined in the OSEK OS v.2.0 rev.1 specification. This is an extension of OSEK OS. 8.4 Alarms The alarm management is built on top of the counter management. The alarm management allows the user to perform link task activation or User's Manual 96 OSEK Operating System -- Rev 1.2 Counters and Alarms MOTOROLA Examples of possible alarm usage are: - `Activate a certain task, after the counter has been advanced 60 times', or - `Set a certain event, after the counter has reached a value of 90'. The counter addressed in the first example might be derived from a timer which is advanced every second. The task in the example is then activated every minute. The counter addressed in the second example might be derived from a rotating axle. The event is set on a 90 degree angle. The OSEK OS takes care of the necessary actions of managing alarms when a counter is advanced. Alarms are defined statically as with all other system resources. The assignment of alarms to counters, as well as the action to be performed when an alarm expires (task and event), are also defined statically. An application can use an alarm after it has been defined and assigned to a counter. Alarms may be either in the stop state or running state. To run an alarm, the special system services are used, which set dynamic alarm parameters to start it. Dynamic alarm parameters are * the counter value when an alarm has to expire. * the cycle value for cyclic alarms. An alarm can be started at any moment by means of system services SetAbsAlarm or SetRelAlarm. An alarm will expire (and predefined actions will take place) when a specified counter value is reached. This counter value can be defined relative to the actual counter value or as OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Counters and Alarms 97 A G R E E M E N T The OSEK OS allows the user to set alarms (relative or absolute), cancel alarms and read information out of alarms by means of system services. Alarm is referenced via its symbolic name which is assigned to the alarm statically at the configuration stage. N O N - D I S C L O S U R E event setting to a certain counter value. These alarms can be defined as either single (one-shoot) or cyclic alarms. R E Q U I R E D Counters and Alarms Alarms R E Q U I R E D Counters and Alarms A G R E E M E N T an absolute value. The difference between relative and absolute alarms is the following: * Relative alarm expires when the specified number of counter ticks has elapsed, starting from the current counter value at the moment the alarm was set. * Absolute alarm expires when the counter reaches the specified number of ticks, starting from zero counter value no matter which value the counter had at the moment the alarm was set. If the specified number of ticks is less than the current counter value, the counter will roll over and count until the specified value. If the specified value is greater than the current value, the alarm will expire just after the counter reaches the desired number. This is illustrated by Figure 8-2. In the latter case, the total time until the alarm expires is the sum of T1 and T2. current counter value 0 specified absolute value maximum allowed counter value T1 N O N - D I S C L O S U R E specified current absolute value counter value 0 T2 T1 Figure 8-2. Two cases for the absolute alarm If a cycle value is specified for the alarm, it is logged on again immediately after expiry with this relative value. Specified actions (task activation or event setting) will occur when the counter counts this number of ticks, starting from the current value. This behavior of the cyclic alarm is the same both for relative and absolute alarms. If the cycle value is not specified (it equals zero) the alarm is considered as a single one. User's Manual 98 OSEK Operating System -- Rev 1.2 Counters and Alarms MOTOROLA The following system configuration options affect the counter and alarm management: * Counters This option defines whether counters are provided by the OS or not. * CounterSize This option defines the size of all counters. The valid values are 8, 16 and 32 which conform to the byte, word or long word size of counters. * Alarms This option defines whether alarms are provided by the OS or not. * AlarmList If this option is turned on, the running alarms are linked into a list which decreases the time for alarm handling. * AlarmDeltaList If this option is turned on, the running alarms are linked into an ordered alarm delta-list which significantly decreases the time for CounterTrigger service if too many alarms are connected with the same counter (more than 10). The time for alarm management services will be increased. Note that this option will be turned off if the AlarmList option is turned on. * CyclicAlarm If this option is turned on, the cyclic alarms are supported. Otherwise, no one alarm may be cyclic, which decreases RAM usage for alarm control blocks as well as decreasing code usage, and advances timing of alarms services. This option is turned on by default. * MinAlarmRAM If this option is turned on, the alarm handling is optimized for memory (RAM). Otherwise, alarm handling is optimized for speed. When turned OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Counters and Alarms 99 A G R E E M E N T 8.5.1 Configuration Options N O N - D I S C L O S U R E 8.5 Programming Issues R E Q U I R E D Counters and Alarms Programming Issues on, the alarm control block is significantly decreased, especially when AlarmList option is turned off. This option is turned off by default. 8.5.2 Data Types The following data types are established by OSEK OS to work with counters: N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Counters and Alarms * CtrRefType the data type references a counter * TickType the data type represents a counter value in system ticks * TickRefType the data type references data corresponding to the data type TickType * CtrInfoType this data type represents a structure for storage of counter characteristics. This structure has the following fields: - maxallowedvalue maximum possible allowed count value; - ticksperbase number of ticks required to reach a counter-specific significant unit; - mincycle minimum allowed number of ticks for a cyclic alarm (only for system with Extended Status). All fields have the data type TickType. The following code may illustrate usage of this data type: CtrInfoType CntData; TickType maxV, minC, cons; GetCounterInfo( CntID, &CntData ); maxV = CntData.maxallowedvalue; minC = CntData.ticksperbase; cons = CntData.mincycle; * CtrInfoRefType this data type references data corresponding to the data type CtrInfoType. The following data type is established by OSEK OS to work with alarms: User's Manual 100 OSEK Operating System -- Rev 1.2 Counters and Alarms MOTOROLA * AlarmBaseType this data type represents a structure for storage of alarm characteristics. It is the same as CtrInfoType; * AlarmBaseRefType this data type references data corresponding to the data type AlarmBaseType; * AlarmType the data type represents an alarm element. To generate a counter in an application, the COUNTER definition is used, it looks like the following: COUNTER <CounterID> { MINCYCLE = <mincycle>; MAXALLOWEDVALUE = <maxallowedvalue>; TICKSPERBASE = <ticksperbase>; }; To define system timer hardware-specific parameters, the following properties should be defined in the OS definition statement: OS <name> { ..... SysTimer = <SysTimerSupport>; HardwareType = <TypeOfTimer>; Prescaler = <PrescalerDefined>; PrescalerValue = <PrescalerValue>; TimerModulo = <TimerModuloDefined>; TimerModuloValue = <TimerModuloValue>; ..... }; The system timer hardware parameters are described in detail in the section Section 13.3.5 Counters and Alarms Related Attributes. ALARM <AlarmID> { ACTION = <Acion>; COUNTER = <CounterID>; TASK = <TaskID>; [ EVENT = <Event>; ] }; OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Counters and Alarms 101 N O N - D I S C L O S U R E A G R E E M E N T 8.5.3 Counters and Alarm Generation R E Q U I R E D Counters and Alarms Programming Issues R E Q U I R E D Counters and Alarms Detailed counter and alarm generation statements are described in Section 13.8 Counter Definition and Section 13.9 Alarm Definition. The declaration statements DeclareCounter and DeclareAlarm should be used to declare an element (counter or alarm) before it is used: DeclareCounter( CtrRefType <CounterID> ) DeclareAlarm looks like the following: A G R E E M E N T DeclareAlarm( AlarmType <AlarmID> ) These declarations are equivalent to the external declaration of variables. 8.5.4 Run-time Services OSEK OS grants a set of services for the user to manage counters and alarms. Detailed descriptions of these services are provided in Section 17 System Services. Here only a brief list is given. Table 8-1. Counter and Alarm Management Run-time Services Service Name N O N - D I S C L O S U R E InitCounter Description Sets the initial value of the counter CounterTrigger Increments the counter value GetCounterValue Gets the counter current value GetCounterInfo AdvanceCounter(1) Gets counter parameters Alternatively increments the value of a counter SetRelAlarm Sets the alarm with a relative start value SetAbsAlarm Sets the alarm with an absolute start value CancelAlarm Cancels the alarm: the alarm is transferred into the STOP state GetAlarm Gets the time left before the alarm expires GetAlarmBase Gets alarm parameters 1. This service is not defined in the OSEK OS v.2.0 rev.1 specification. This is an extension of OSEK OS. User's Manual 102 OSEK Operating System -- Rev 1.2 Counters and Alarms MOTOROLA 8.5.5 Constants For the system counter, which is always a time counter, special constants are provided by the operating system: OSMAXALLOWEDVALUE maximum possible allowed value of the system timer in ticks; * OSTICKSPERTIME, number of ticks that are required to reach 10 OSTICKPERBASE milliseconds in the system counter; * OSTICKDURATION duration of a tick of the system counter in nanoseconds; * OSMINCYCLE minimum allowed number of ticks for a cyclic alarm (only for system with Extended Status). N O N - D I S C L O S U R E * A G R E E M E N T Examples of the run-time service usage are provided in Section 17 System Services. R E Q U I R E D Counters and Alarms Programming Issues OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Counters and Alarms 103 N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Counters and Alarms User's Manual 104 OSEK Operating System -- Rev 1.2 Counters and Alarms MOTOROLA 9.2 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105 9.3 Events and Scheduling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .106 9.4 Programming Issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108 9.2 General Within the OSEK operating system, tasks can be synchronized via occupation of a resource (see Section 7 Resource Management). Another means of synchronization is the event mechanism, which is provided for Extended Tasks only. Special fields in the task node of an Extended Task are provided for event management in the OSEK OS (see Section 4.7.2 Task Control Block). Events are the only mechanism allowing a task to enter the waiting state. An event is an object managed by the OSEK Operating System, which is able to store binary data. The interpretation of the event is up to the user. Examples are: the signalling of a timer's expiry, the availability of a resource, the receipt of a message, etc. Within the operating system, events are not independent objects, but allocated to Extended Tasks. Each Extended Task has a definite number of events - 8 or less (in fact, the byte size is used for event management in the current OSEK OS implementation.). Events are represented by two event masks - byte-sized fields in the task node (See Section 4.7.2 Task Control Block). One field is the mask of events the task is waiting for. This mask can be set and cleared only by the task-'owner' (a `private' mask). The second field (a `public' mask) contains the mask of the events, which are set for the task by other tasks. When activating an Extended Task, all its events are cleared. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Events 105 R E Q U I R E D 9.1 Contents A G R E E M E N T Section 9. Events N O N - D I S C L O S U R E User's Manual -- OSEK Operating System R E Q U I R E D Events N O N - D I S C L O S U R E A G R E E M E N T An Extended Task can wait for several events simultaneously and setting at least one of them causes the task to be transferred into the ready state. When a task wants to wait for one event or several ones, the corresponding bits in its `private' event mask are set. The system service WaitEvent is designed to force a task to wait for an event. When another task sets an event, it sets the specified bits of the `public' event mask, and if some bits in both `private' and `public' masks are the same, the task is transferred into the ready state. The task can clear its own events by clearing the `private' event mask. Various system services are available to manipulate events, depending on whether the dedicated task is the `owner' of the event or another task, which does not necessarily have to be an Extended Task. All tasks can set any events of any Extended Task. Only the appropriate Extended Task (the owner of the particular event mask) is able to clear events and to wait for the setting (receipt) of events. Basic Tasks must not use the operating system services for clearing events or waiting for them. An alarm can also be set for an Extended Task, which sets an event at a certain time. Thus, the Extended Task can delay itself (see example in Section 17.7.7 Examples of Using Events). It is not possible for an interrupt service routine or a Basic Task to wait for an event, since the receiver of an event is an Extended Task in any case. On the other hand, any task or ISR can set an event for an Extended Task, and thus inform the appropriate Extended Task (its identification must be known) about any status change via this event. To have events in the system, the configuration option Events must be turned on. 9.3 Events and Scheduling An event is an exclusive signal which is assigned to an Extended Task. For the scheduler, events are the criteria for the transition of Extended Tasks from the waiting state into the ready state. The operating system provides services for setting, clearing and interrogation of events, and for waiting for events to occur. User's Manual 106 OSEK Operating System -- Rev 1.2 Events MOTOROLA Scheduler Event of Extended task 1 set reset Extended task 1 waiting Extended task 2 running reset running set event reset event wait for event ready waiting running Figure 9-1. Synchronization by events in case of full-preemptive scheduling If non-preemptive scheduling is supposed, rescheduling does not take place immediately after the event has been set, as shown in Figure 9-2. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Events 107 A G R E E M E N T Figure 9-1 illustrates the procedures which are effected by setting an event: Extended Task 1 (with higher priority) waits for an event. Extended Task 2 sets this event for Extended Task 1. The scheduler is activated. Subsequently, Task 1 is transferred from the waiting state into the ready state. Due to the higher priority of Tasks 1 this results in a task switch, Task 2 being preempted by Task 1. Task 1 resets the event. Thereafter Task 1 waits for this event again and the scheduler continues execution of Task 2. N O N - D I S C L O S U R E Extended Tasks are in the waiting state if an event for which the task is waiting has not occurred. If an Extended Task tries to wait for an event and this event has already occurred, the task remains in the running state. R E Q U I R E D Events Events and Scheduling N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Events Scheduler Event of Extended task 1 set reset Extended task 1 waiting reset ready Extended task 2 running set event rescheduling reset event running wait for event waiting running ready Figure 9-2. Synchronization by events in case of full-preemptive scheduling 9.4 Programming Issues 9.4.1 Configuration Options The only system configuration option Events controls event management in the system. If it is turned off events are not implemented. 9.4.2 Data Types The OSEK Operating System establishes the following data types for the event management: * EventMaskType * EventMaskRefType The data type to refer to an event mask. The data type of the event mask; The only data types must be used for operations with events. 9.4.3 Events Definition To generate a counter in an application the EVENT definition is used, it looks like the following: EVENT <Event> { User's Manual 108 OSEK Operating System -- Rev 1.2 Events MOTOROLA MASK = 0x01; }; To refer to an event the declaration statement DeclareEvent should be used to declare the event before it is used. DeclareEvent looks like the following: DeclareEvent( EventMaskType <Event> ) R E Q U I R E D Events Programming Issues Table 9-1. Event Management Run-time Services Service Name SetEvent ClearEvent Description Sets events of the given task according to the event mask Clears events of the calling task according to the event mask GetEvent Gets the current event setting of the given task WaitEvent Transfers the calling task into the waiting state until specified events are set Examples of the run-time services usage are provided in section Section 17.7 Event Management Services. 9.4.5 Additional Usage Note that it is possible to use bits in memory fields assigned for events for some internal task's needs as bit flags. In case of using events in the system in every Extended task's control block special fields are created. If a task uses less than eight events, it is possible to use SetEvent and ClearEvent system services with appropriate masks to manipulate the internal task's bit flags. See the following example: DeclareTask( TASK_A ) DeclareTask( TASK_C ) OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Events 109 N O N - D I S C L O S U R E OSEK OS grants a set of services for the user to manage events. A detailed description of these services is provided in Section 17.7 Event Management Services. Here only a brief list is given. A G R E E M E N T 9.4.4 Run-time Services R E Q U I R E D Events DeclareEvent( DeclareEvent( DeclareEvent( DeclareEvent( /* /* /* /* /* /* X_FLG ) Y_FLG ) Z1_FLG ) Z2_FLG ) event masks for internal flags */ (generated by SG tool) */ 0x80 */ 0x40 */ 0x20 */ 0x10 */ A G R E E M E N T TASK( TASK_A ) { EventMaskType x, y, z1, z2; z1 = Z1_FLG; z2 = Z2_FLG; int speed; ... if (speed == LIMIT) { x = X_FLG; SetEvent( TASK_A, x ); } GetEventMask( TASK_A, &x ); if ((x & X_FLG) != 0 ) ClearEvent( z1 ); else SetEvent( TASK_A, z2 ); if ((x & Y_FLG) == 0 ) ChainTask( TASK_C ); ... } N O N - D I S C L O S U R E In the example the task uses four most significant bits of the event field as its internal bit flags. Least significant bits are free and they can be used for `external' OSEK OS events. But such approach requires more attention from the user to avoid occasionally changing of `internal' events instead of `external' ones and visa versa. Note that access to that binary data is performed only via the system services for event management. User's Manual 110 OSEK Operating System -- Rev 1.2 Events MOTOROLA 10.2 Message Concept. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111 10.3 Unqueued Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113 10.4 Queued Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .115 10.5 Programming Issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116 10.2 Message Concept In the OSEK Operating System, communication between application tasks takes place via messages. Communication concept and message management system services are based on the `OSEK Communication' v. 2.1, revision 1, June 1998. Messages are stored in Message Objects (MO) which are handled by the operating system. A distinction is made between the following: * Unqueued Messages and * Queued Messages An Unqueued Message represents the current value of a system variable, e.g. engine temperature, wheel speed, etc. Unqueued Messages are not buffered but overwritten with their actual values. The receive operation reads the Unqueued Message value. Thereby the message data is not consumed. In contrast, a Queued Message contains an event information, e.g. `engine temperature exceeds a certain limit'. Queued Messages are buffered with the send operation and consumed with a receive operation. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Communication 111 R E Q U I R E D 10.1 Contents A G R E E M E N T Section 10. Communication N O N - D I S C L O S U R E User's Manual -- OSEK Operating System R E Q U I R E D Communication In OSEK OS, message objects are referenced by tasks via the unique identifiers defined by the user at the configuration stage. The OSEK Operating System ensures data consistency of message data during task operation, uniform in all types of scheduling. The received message data remains unchanged until a further receive operation is performed, unless the task or function using the data overwrites the data with a direct access operation. A G R E E M E N T OSEK supports two types of communication between tasks: 1:1 and 1:N communication. * 1:1 communication means that only one task receives the message; * 1:N communication means that N tasks receive the same message. Both types of messages, Unqueued and Queued Messages, can be used for 1:1 and 1:N communication, for local (ECU-internal) and network communication. N O N - D I S C L O S U R E As an option, task activation or event signalling can be defined statically to be performed at message arrival to notify a task. Task activation or event signalling can be used to inform tasks that want to act immediately on new message information. There is no special operating system service to wait for messages, but the normal event mechanism is used. Only one notification method can be assigned for certain messages. Alarms can be assigned statically to message objects (only one alarm per message object). If the message does not arrive during the time period specified via the ALARMRESETTIME property in the MESSAGE definition statement, the alarm counter expires and an associated task is activated or an event is signalled. Whenever a message arrives, the alarm is restarted. This feature can be used to supervise whether Unqueued Messages are updated or Queued Messages arrive on time. It is possible to assign both an alarm and task notification (task activation or event signalling) to a particular message object. User's Manual 112 OSEK Operating System -- Rev 1.2 Communication MOTOROLA R E Q U I R E D Communication Unqueued Messages Table 10-1. Features of the Message Concept Unqueued Message QueuedMessage No buffering Buffering in a FIFO-queue No consumption of message Consumption of messages Direct access possible in non-preemptive systems (no copies) No direct access possible (always copies) Static definition of task activation or event signalling 10.3 Unqueued Messages Unqueued Messages represent the current value of a state variable. Tasks can have three various access type to Unqueued Messages - read only (receive), write only (send) and full read/write access. The send operation overwrites the current value of a message, i.e. Unqueued Messages are not buffered. The receive operation reads the current value of a Unqueued Message whereby the message data is not consumed. These services ensure: * the consistent writing and reading of message data within the send and receive operation (also in preemptive systems) and * the consistency of data while tasks and functions (subprograms) use the message data. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Communication 113 N O N - D I S C L O S U R E OSEK OS communication services provide all means for local message transfer within single ECU. To transfer data over the network, the OSEK Communication System (COM) will be used, which is designed to handle all other types of communication through the network. And OSEK OS communication services provide an interface for application tasks to exchange data. Thus, messages serve as interface for both ECU internal and network communication. Uniform services with identical interfaces are offered (network transparency). A G R E E M E N T Static definition of a message alarm R E Q U I R E D Communication An Unqueued Message can have a default value which is assigned statically to the message at the configuration stage. This value is returned when the message is received first time without prior send operation (see Section 13.10.1 Object Attributes and example in Section 10.5.5 Usage of Messages for details regarding Unqueued Message default value). N O N - D I S C L O S U R E A G R E E M E N T Unqueued Messages may be either with or without a local copy of a message. It indicates statically with message property WithCopy set to TRUE or set to FALSE respectivelly. Last case is called WithoutCopy for convenience. The distinction between these kinds of Unqueued Messages is the following: * When the WithCopy configuration is used, the Unqueued Message item is copied from the task data space into the message item for send operation, and from the message item to the task data space for receive operation. The message body is copied consistently, i.e. the operating system provides atomic behavior of the send-receive operations. The default value is copied from the user's-defined area into the message body during system start-up. * When the WithoutCopy configuration is used, the Unqueued Message item is not copied from the task data space into the message item. Instead, the task-sender updates the message body directly via de-referencing of the pointer and writing the data at the pointer address, and the task-receiver uses the message body by means of de-referencing the pointer and reading the data. The operating system doesn't provide atomic behavior of the send-receive operations, and this consistency is to be provided by the user's code. Unqueued Messages are used similar to C-language variables (direct access e.g. in a C-language assignment or in a C-language expression). The access privileges (send, receive or send/receive) defined for a message also determine which direct access operations are allowed. 1:N communication for Unqueued Messages does not have any difference from 1:1 communication, since any task can read the Unqueued Messages if its identifier is known. User's Manual 114 OSEK Operating System -- Rev 1.2 Communication MOTOROLA In contrast to Unqueued Messages, Queued Message objects can temporarily store several messages. The temporary storage follows the FIFO principle, i.e. messages are received in the same order as they were sent. During the send operation the message item is copied from the task data space into the message FIFO area at the write pointer. During the read operation the message item is copied from the FIFO area at the read pointer into the receiving task space. The data is copied consistently, i.e. the operating system provides atomic behavior of the send-receive operations. The FIFO area is circular. It is illustrated in Figure 10-1. Message "msg1" is consumed from the Queued Message object by a task, and other message items are "moved" in the Queued MO towards the top (in fact, read and write pointers are changed). After the message item "msg1" was consumed, new message "msg5" is written by a task at the empty location (the last one). If an Queued Message object has no memory capacity left to store the new message, the oldest message is overwritten - in Figure 10-1 "msg2" is overwritten by the message item "msg6" in spite that "msg2" has not been consumed. The overwriting process is indicated both to sender and receiver in systems with Extended Status by means of return codes while send or receive services are executed by a task. A Queued Message is characterized by the length of a single message item and by the depth of a queue. These parameters are defined by the user at the configuration stage. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Communication 115 A G R E E M E N T 10.4 Queued Messages N O N - D I S C L O S U R E To have Unqueued Messages in the system the configuration option UnqueuedMessages must be turned on. R E Q U I R E D Communication Queued Messages R E Q U I R E D Communication "msg1" is consumed "msg1" by a task read pointer ... "msg2" write pointer A G R E E M E N T N O N - D I S C L O S U R E read pointer "msg3" "msg4" read pointer "msg2" "msg3" write pointer "msg2" write pointer "msg3" "msg4" ... 1 "msg4" "msg5" 3 2 "msg5" "msg6" New message "msg5" is written by a task into the Queued MO New message "msg6" will overwrite "msg2" of the Queued MO Figure 10-1. Operations with Queued Messages Event communication includes an implicit synchronization of the communication partners since an Queued Message must be sent before it can be received. When the receive operation is performed, an Queued Message is removed from the message object and is thus consumed. In case of multiple receivers (1:N communication) OSEK OS ensures that no receiver may receive a new message, until all receivers will complete the reception of the current message. The last receiver consumes the message. To have Queued Messages in the system, the configuration option QueuedMessages must be turned on. 10.5 Programming Issues 10.5.1 Configuration Options The following system configuration options are intended to control communication features: User's Manual 116 OSEK Operating System -- Rev 1.2 Communication MOTOROLA * UnqueuedMsgDefaultValue This option allows Unqueued Messages to have default values; * QueuedMessages This option allows Queued Messages in the system; * QueuedMsgOneToN If this option is turned on, 1:N Queued Messages are allowed; * ActivateOnMsg If this option is turned on task activation on message arrival is supported; * AlarmOnMsg If this option is turned on an alarm can be linked to message arrival; * SetEventOnMsg If this option is turned on event setting is allowed on message arrival. 10.5.2 Identifiers The following names are used in the OSEK Operating System for work with messages: * SymbolicName This is an unique name representing a message. It only can be used in conjunction with calls of the message service. A SymbolicName need not be a data type. Variables or constants of SymbolicName can be declared or used. AccessName This is a unique name defining access to a message object. Depending on the chosen configuration, a distinction is made between the following AccessName scheme: WithCopy configuration: A application variable exists as a local copy of the message. The name of the * OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Communication 117 A G R E E M E N T This option allows Unqueued Messages in the system; N O N - D I S C L O S U R E * UnqueuedMessages R E Q U I R E D Communication Programming Issues variable is the AccessName. This variable contains a copy of the corresponding message object. WithoutCopy configuration: The message object data is accessed via the AccessName. This AccessName is a static link: it refers directly to the message object data. The AccessName refers to the same data (RAM) as the message object. 10.5.3 Message Definition Each message in an application is generated by means of using statements like the following: MESSAGE <MsgName> { ACTION = <MessageAction>; TYPE = <MessageType>; ITEMTYPE = <type>; ITEMS = <BufferSize>; ALARMRESETTIME = <TimeOut>; ALARMRESET = <AlarmId>; StartupAlarm = <Start>; TASK = <TaskId>; EVENT = <EventMask>; ReceiverNum = <NumberOfReceivers>; DefaultValue = <InitialValue>; }; N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Communication The MESSAGE definition statement defines either Unqueued or Queued message according to TYPE property setting. The TASK and EVENT references are designed to link the action with the message arrival. The ALARMRESET attribute is used to link an alarm with message arrival - when the message arrives the alarm is restarted. In detail message configuration statements is described in Section 12 System Configuration. There is no constructional elements defined for messages. User's Manual 118 OSEK Operating System -- Rev 1.2 Communication MOTOROLA 10.5.4 Run-time Services OSEK OS grants a set of services for the user to manage tasks. Detailed descriptions of these services are provided in section Section 17.8 Communication Management Services. Here only a brief list is presented. Table 10-2. Task Management Run-time Services SendMessage ReceiveMessage GetMessageResource ReleaseMessageResource GetMessageStatus Description Updates the unqueued message Gets the unqueued message Sets the given message object status as busy if it is not already so Sets off the message object from busy Returns the current status of the message Examples of the run-time services usage are provided in Section 17 System Services. A G R E E M E N T Service Name R E Q U I R E D Communication Programming Issues Messages are identified via a symbolic name. This identifier is used for references to the message when the system service is used. If the message is used in the WithCopy configuration, then the variable to hold message data is defined within the user's code by means of using the regular C-language definitions. Because system generator always create typedef declaration for every message, it is recommended to use this declaration for definition of variables which hold message data. By convention, this typedef consists of prefix OSMSG and name of the message <MsgName>, defined in MESSAGE description in OIL file. For example, if the user defines the message MsgA having type int, then user's code may access message using the following statements: OSMSGMsgA _MsgA; ReceiveMessage( MsgA, _MsgA ); OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Communication 119 N O N - D I S C L O S U R E 10.5.5 Usage of Messages R E Q U I R E D Communication if( _MsgA == 2 ) { _MsgA = 1; } SendMessage( MsgA, _MsgA ); If the message is configured without WithCopy property, then the pointer to the message body should be defined within the user's code using regular C-language statements. Again, because system generator creates typedef declaration for message item, it is recommended to use this declaration for definition of pointer, which is used access message data. A G R E E M E N T For example, if the user defines the WithoutCopy message MsgB, having the type int, then user's code may access message using the following statements: OSMSGMsgB*_MsgB = (OSMSGMsgB*)&OSMsgB->msg; ReceiveMessage( MsgB, _MsgB ); if( *_MsgB == 2 ) { *_MsgB = 1; } SendMessage( MsgB, _MsgB ); The following example demonstrates Unqueued Message default value definition. const int /* Source C-file */ myMsgADefValue = 0; /* MsgA default value */ N O N - D I S C L O S U R E /* Configuration OIL-file */ MESSAGE MsgA { TYPE = UNQUEUEDMESSAGE; ITEMTYPE = "int"; ITEMS = 1; DefaultValue = "&myMsgADefValue"; }; User's Manual 120 OSEK Operating System -- Rev 1.2 Communication MOTOROLA 11.2 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121 11.3 Hook Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121 11.4 Error Handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .126 11.5 Start-up Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .128 11.6 Application Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .130 11.7 System Shutdown. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .130 11.8 Programming Issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131 11.2 General The OSEK Operating System provides the user with tools for error handling and simple debugging at run time. These are special hook routines with names specified by OSEK OS that are to be developed by the user. In this section, error handling at the system configuration stage is not considered; it is described in Section 12 System Configuration. 11.3 Hook Routines The OSEK Operating System supports system specific hook routines to allow user-defined actions within the OS internal processing. These hook routines in OSEK OS are: * Called by the operating system, in a special context depending on the implementation of the operating system; OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Error Handling and Special Routines 121 R E Q U I R E D 11.1 Contents A G R E E M E N T Section 11. Error Handling and Special Routines N O N - D I S C L O S U R E User's Manual -- OSEK Operating System A G R E E M E N T R E Q U I R E D Error Handling and Special Routines * Higher priority than all tasks; * Using an implementation-dependent calling interface; * Part of the operating system, but user defined; * Implemented by the user; * Standardized in interface per OSEK OS implementation, but not standardized in functionality (environment and behavior of the hook routine itself), therefore usually hook routines are not portable; * Only allowed to use a subset of API functions; * Optional. N O N - D I S C L O S U R E In the OSEK OS hook routines are intended for * System startup. The corresponding hook routine (StartupHook) is called after the operating system startup and before the scheduler is running; * Tracing or application dependent debugging purposes as well as user defined extensions of the context switch; * Error handling. The corresponding hook routine (ErrorHook) is called if a system call returns a value not equal to E_OK; * System shutdown. The corresponding hook routine (ShutdownHook) is called. The OSEK OS provides the following hook routines - ErrorHook, PreTaskHook, PostTaskHook, StartupHook, ShutdownHook, IdleLoopHook1. The user must create the code of these routines, OSEK OS only provides description of function prototypes. * ErrorHook - this hook is called by the Operating System at the end of a system service which has a return value not equal to E_OK (see Section 11.4.1 Error Interface). It is called before returning to the task level or the ISR level. 1. IdleLoopHook hook routine is not introduced in OSEK OS standard. It is an extension of OSEK OS. User's Manual 122 OSEK Operating System -- Rev 1.2 Error Handling and Special Routines MOTOROLA * PostTaskHook - This hook is called after the operating system leaves the context of the task. It is called from the scheduler when it switches from the current task to another. It may be used by the application to trace the sequences and timing of tasks' execution. * StartupHook - This hook is called after the operating system startup and before the scheduler is running. It may be used by the application to perform initialization actions, task activation, alarm setting. * ShutdownHook - This hook is called when the service ShutdownOS has been called. It is called before the Operating System shuts down itself. * IdleLoopHook - This hook is called from scheduler idle loop (see Section 5.2 General). It is not possible to call any OSEK OS directives from this hook. Hardware dependent code (like manipulation with COP registers) may be placed here. Time stamps can be integrated individually into the application software with the help of hook routines OSPreTask and OSPostTask. The user can set time stamps enabling him to trace the program execution at the following locations before calling operating system services: * When activating or terminating tasks; * At explicit points of rescheduling ( ChainTask, Schedule); The Operating System does not need to include a time monitoring feature which ensures that each task or a specific task, e.g. with the lowest priority, has been activated after a defined maximum time period. The user can optionally use the hook routines or establish a watchdog task that takes `one-shot displays' of the operating system status. See examples of programming techniques using the hook routines in Section 17.9 Operating System Execution Control. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Error Handling and Special Routines 123 A G R E E M E N T PreTaskHook - this hook is called before the operating system enters the context of the task. This hook is called from the scheduler when it passes control to the given task. It may be used by the application to trace the sequences and timing of the tasks' execution. N O N - D I S C L O S U R E * R E Q U I R E D Error Handling and Special Routines Hook Routines R E Q U I R E D Error Handling and Special Routines Some system services may be called by the hook routines: Table 11-1. OSEK OS system services for hook routines Hook routines A G R E E M E N T Service Error Hook PreTask Hook PostTask Hook Startup Hook Shutdown Hook DeclareTask allowed allowed allowed allowed allowed ActivateTask -- -- -- allowed -- TerminateTask -- -- -- -- -- ChainTask -- -- -- -- -- Schedule -- -- -- -- -- GetTaskId allowed(1) allowed allowed -- -- allowed allowed allowed -- -- allowed(2) allowed allowed -- -- EnterISR -- -- -- -- -- LeaveISR -- -- -- -- -- EnableInterrupt -- -- -- -- -- DisableInterrupt -- -- -- -- -- allowed allowed allowed -- -- DeclareResource -- -- -- -- -- GetResource -- -- -- -- -- ReleaseResource -- -- -- -- -- allowed allowed allowed -- -- SetEvent -- -- -- -- -- ClearEvent -- -- -- -- -- GetEvent allowed allowed allowed -- -- WaitEvent -- -- -- -- -- InitCounter -- -- -- -- -- CounterTrigger -- -- -- -- -- AdvanceCounter -- -- -- -- -- GetCounterValue -- -- -- -- -- GetTaskState GetTCBInfo N O N - D I S C L O S U R E GetInterruptDescriptor DeclareEvent User's Manual 124 OSEK Operating System -- Rev 1.2 Error Handling and Special Routines MOTOROLA Table 11-1. OSEK OS system services for hook routines Hook routines PreTask Hook PostTask Hook Startup Hook Shutdown Hook -- -- -- -- -- DeclareAlarm allowed allowed allowed -- -- GetAlarmBase allowed allowed allowed -- -- GetAlarm allowed allowed allowed -- -- SetRelAlarm -- -- -- -- -- SetAbsAlarm -- -- -- -- -- CancelAlarm -- -- -- -- -- SendMessage -- -- -- -- -- allowed for unqueued messages -- -- -- -- GetMessageResource -- -- -- -- -- ReleaseMessageResource -- -- -- -- -- GetMessageStatus allowed -- -- -- -- GetActiviveApplicationMode allowed allowed allowed allowed allowed StartOS -- -- -- -- -- ShutdownOS -- -- -- -- -- GetCounterInfo ReceiveMessage A G R E E M E N T Error Hook 1. It may happen that currently no task is running. In this case the service returns the task Id INVALID_TASK. 2. It may happen that currently no task is running. In this case the service returns E_NOFUNC return value if OSEK OS has the Extended Status. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Error Handling and Special Routines 125 N O N - D I S C L O S U R E Service R E Q U I R E D Error Handling and Special Routines Hook Routines NOTE: It is not possible to call any OSEK OS services from IdleLoopHook hook routine. 11.4 Error Handling 11.4.1 Error Interface The hook routine ErrorHook is provided to handle temporarily and permanently occurring errors within the OSEK Operating System. Its basic framework is predefined and must be completed by the user. This gives the user a choice of efficient centralized or decentralized error handling. A G R E E M E N T R E Q U I R E D Error Handling and Special Routines N O N - D I S C L O S U R E Three different kinds of errors are distinguished in OSEK OS: * Application errors - the Operating System could not execute the requested service correctly, but assumes the correctness of its internal data. In this case, centralized error treatment is called. Additionally, the Operating System returns the error by the status information for decentralized error treatment. * Fatal errors - the Operating System can no longer assume correctness of its internal data. In this case OSEK OS calls the centralized system shutdown. The special system routine ShutdownOS is intended to shut down the system in case of the fatal error. ShutdownOS may be called both by the user and by the system on experiencing a fatal error. These service routines are provided by the OSEK Operating System as opposed to the ErrorHook routine, which should be written by the user. User hook ShutdownHook is called by ShutdownOS. The OSEK OS error service is called with a parameter that specifies the error. It is up to the user to decide what to do, depending on which error has occurred. The OSEK Operating System specifies the following errors: User's Manual 126 OSEK Operating System -- Rev 1.2 Error Handling and Special Routines MOTOROLA R E Q U I R E D Error Handling and Special Routines Error Handling Table 11-2. OSEK OS Error codes Value Description E_OK 0 No error, successful completion E_OS_ACCESS 1 Access to the service/object denied E_OS_CALLEVEL 2 Access to the service from the ISR is not permitted E_OS_ID 3 The object ID is invalid E_OS_LIMIT 4 The limit of services/objects exceeded E_OS_NOFUNC 5 The object is not used, the service is rejected E_OS_RESOURCE 6 The task still occupies the resource E_OS_STATE 7 The state of the object is not correct for the required service E_OS_VALUE 8 A value outside of the admissible limit E_OS_SYS_STACK 10 A G R E E M E N T Common Error Codes Internal stack overflow E_COM_BUSY 1 Message in use by application task/function E_COM_ID 3 Invalid message name passed as parameter E_COM_LIMIT 4 Overflow of FIFO associated with queued messages E_COM_LOCKED 7 Rejected service call, message object locked due to a pending operation E_COM_NOMSG 9 No message available Errors committed by the user in direct conjunction with the Operating System can be intercepted to a large extent via the Extended Status of the Operating System, and displayed. This results in an extended plausibility check on calling OS services. 11.4.2 Extended Status The OSEK Operating System version with Extended Status requires more execution time and memory space than the run time version, due to the additional plausibility checks it offers. However, many errors can be found in a test phase. After they have all been eliminated, the system can be recompiled with the run time version. The following example can illustrate Extended Status usage: OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Error Handling and Special Routines 127 N O N - D I S C L O S U R E Error Name N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Error Handling and Special Routines * If a task is activated in the run time, either `OK' or `Task already activated' is returned. Moreover, in the Extended Status version, the additional status like `Task not defined', `Maximum number of tasks already activated' or `Stack overflow', etc. can be returned. These extended messages must no longer occur in the target application at the time of execution, i.e., the corresponding errors are not intercepted in the operating system's run time version. 11.4.3 Possible Error Reasons Errors in the application software are typically caused by: * Errors on handling the operating system, i.e. incorrect configuration / initialization / dimensioning of the operating system or non-observance of restrictions regarding the OS service. * Error in software design, i.e. unwise choice of task priorities, generation of deadlocks, unprotected critical sections, incorrect dimensioning of time, inefficient conceptual design of task organization, etc. 11.5 Start-up Routine The special system routine StartOS is implemented in the OSEK Operating System to allocate and initialize all dynamic system and application resources in RAM. These routines are called from the main() function of the application with the application mode as parameter (see Section 11.6 Application Modes) and pass the control to the scheduler to schedule the first task to be running. User hook StartupHook is called after operating system startup and before the scheduler is running. See Appendix A Sample Application for details. The figure below shows system startup. User's Manual 128 OSEK Operating System -- Rev 1.2 Error Handling and Special Routines MOTOROLA OS executes first user hardwarecall to operation OS executes OS kernel task is specific StartOS system StartupHook is running running initialization code initialization code During StartupHook all user interrupts are disabled Figure 11-1. System startup in the OSEK OS N O N - D I S C L O S U R E After returning from the StartupHook hook routine, the operating system enables interrupts according to INITIAL_INTERRUPT_DESCRIPTOR (see Section 6.7.6 Constants), and starts the scheduler. A G R E E M E N T (Re-)Start R E Q U I R E D Error Handling and Special Routines Start-up Routine OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Error Handling and Special Routines 129 11.6 Application Modes Application modes are supported to allow OSEK OS to come under different modes of operation. The minimum number of application modes is one (SG tool generates an application mode with name "Mode" by default). Once the operating system has been started, it is not allowed to change the application mode. Each application mode consists of its own set of tasks. There is no limitation to having a task or ISR running in different modes. Sharing a task/ISR between different modes is recommended if the same functionality is needed again. N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Error Handling and Special Routines NOTE: If the system is running in a specific application mode, then it is not possible to affect a task from another application mode (it may lead to inappropriate application behavior). Special OIL statements should be used to define different application modes (see Section 13.12 Different Application Modes Definition). After system shutdown, it is possible to start an application in another application mode (with another set of tasks), therefore run-time reconfiguration is supported. NOTE: After application re-start either in the same or in another application mode internal OSEK OS data will only be initialized. The user is responsible for proper initialization of user's data on application re-start. NOTE: Application mode consists of own set of tasks. All other OSEK OS system objects like Alarms, Messages, Stack Pools etc. are shared between different application modes. 11.7 System Shutdown The special ShutdownOS service exits in OSEK OS to shut down the operating system. This service could be requested by the application or requested by the operating system due to a fatal error. When ShutdownOS service is called with a defined error code, the operating system will shut down and call the hook routine ShutdownHook. The user is free to define any system behavior in ShutdownHook e.g. not to return from the routine. If ShutdownHook User's Manual 130 OSEK Operating System -- Rev 1.2 Error Handling and Special Routines MOTOROLA After the return from ShutdownOS service all interrupts will be disabled. 11.8 Programming Issues 11.8.1 Configuration Options The following configuration options affect error handling and hook routines: * ErrorHook If this option is turned on, the ErrorHook is called by the system for error handling * PreTaskHook If this option is turned on, the PreTaskHook is called by the system before context switching * PostTaskHook If this option is turned on, the PostTaskHook is called by the system before context switching * StartupHook If this option is turned on, the StartupHook is called by the system at the end of the system initialization * ShutdownHook If this option is turned on, the ShutdownHook is called by the system when the OS service ShutdownOS has been called * IdleLoopHook If this option is turned on, the IdleLoopHook is called from scheduler idle loop OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Error Handling and Special Routines 131 A G R E E M E N T NOTE: N O N - D I S C L O S U R E returns, the operating system jumps to the next statement following the initial call to StartOS. After this, the OSEK OS may be started again in a specified application mode. R E Q U I R E D Error Handling and Special Routines Programming Issues N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Error Handling and Special Routines User's Manual 132 OSEK Operating System -- Rev 1.2 Error Handling and Special Routines MOTOROLA 12.2 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .133 12.3 Application Configuration File . . . . . . . . . . . . . . . . . . . . . . . . .134 12.4 OIL Concept . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .134 12.2 General The OSEK Operating System is fully statically configured one. All system properties, the number of system objects and their parameters (characteristics of tasks, counters, alarms, messages, etc.), run time behavior are defined by the user. Such approach allows the user to create various range of applications with exactly defined characteristics. Different memory and performance requirements can be easily satisfied with such modular approach. All application parameters are defined in the special configuration file. This file must conform some grammar rules. It is processed by the separate System Generator utility (SG) 1. The System Generator analyzes statements in the configuration file and builds output C-language files needed to compile and link an application with the specified features. During its execution SG reports to the user about the errors. The System Generator produces header and source code files that defines all properties and objects in terms of the C language. These files are to be compiled and linked together with the user's source code. 1. One version of SG is delivered - the 32-bit version (`sysgen.exe') for Windows NT and Windows 95. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Configuration 133 R E Q U I R E D 12.1 Contents A G R E E M E N T Section 12. System Configuration N O N - D I S C L O S U R E User's Manual -- OSEK Operating System N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D System Configuration 12.3 Application Configuration File Application configuration file contains the statements which define the system properties and objects. Such file can have any extension and the extension `.oil' is suggested by default. The file of this format is processed by the SG utility. As a result of application configuration file processing SG produces three types of standard C-language files as it is described in Section 14.3.1 Application Configuration. SG produces two header files and one source file. These files provides the code for all system tables, descriptors, arrays etc. both in ROM and RAM according to the user specified application configuration. 12.4 OIL Concept OSEK Implementation Language (OIL) is the specially designed language for development of embedded applications based on OSEK concept. OIL is used to describe the application structure (application configuration) as a set of system objects with defined links. OIL allows the user to write an application configuration as a text file. These files have predefined structure and special (standard) grammar rules. All system objects specified by OSEK and relationships between them can be described using OIL. OIL defines standard types for system objects. Each object is described by a set of attributes and references. All keywords, attributes, object names, and other identifiers are casesensitive. 12.4.1 OIL File The OIL file contains two parts - one for the definition of implementation specific features (Implementation Definition) and another one for the definition of the structure of the application located on the particular CPU (Application Definition). In the very beginning of an OIL file the number of the version of OIL is indicated. The keyword OIL_VERSION is used for this purpose. Two OIL User's Manual 134 OSEK Operating System -- Rev 1.2 System Configuration MOTOROLA 12.4.2 Standard OIL Format The Standard OIL is intended to configure OSEK OS Operating System (OS) with single application mode (SG generates single application mode with name `Mode' by default). The Standard OIL is considered to be a part of OSEK OS specification v.2.0. It strictly defined by the "OSEK/VDX System Generation OIL: OSEK Implementation Language", version 2.0, OSEK group, 16.12.1997. 12.4.3 Extended OIL Format Extended OIL format includes extensions needed to control additional features like Object Library, multiple application configuration definition, and Constant Tables. For details regarding Extended OIL format please refer to OSEK Builder User's Manual. To establish different application modes in OSEK OS application it is necessary to use Extended OIl format in application configuration file. 12.4.4 Implementation Definition The Implementation Definition defines implementation specific features for the particular OSEK implementation for which this application is developed. The user can limit the given set of values for object attributes (e.g. restrict the possible OS conformance classes). It is not allowed to exclude any standard attributes from the particular OSEK implementation. Additional non-standard attributes can be defined for the objects for the particular OSEK implementation. If no implementation definition is included in the OIL file then the complete set of standard attributes and standard attribute values is OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Configuration 135 A G R E E M E N T OIL_VERSION = "2.0e"; N O N - D I S C L O S U R E versions are supported at the moment - version 2.0 corresponds to the Standard OIL format and version 2.0e corresponds to the Extended OIL format. For example: R E Q U I R E D System Configuration OIL Concept considered to be defined for the application. Otherwise it defines value ranges for the attributes allowed by the OSEK implementation. If some standard attributes have no restrictions for a particular implementation then the description of this attribute can be omitted in the corresponding implementation definition. The include mechanism (see Section 12.4.5.2 Include Directive) can be used to define the implementation definition as a separate file. Thus corresponding implementation definition files can be developed and delivered with particular OSEK implementations and then included in user's OIL files. The Motorola OSEK OS implementation is described in the "mot20.oil" file which are delivered in the package. 12.4.4.1 Implementation Definition Grammar Implementation Definition part starts with keyword IMPLEMENTATION and implementation name. The structure for Implementation Definition part is shown using the following syntax: IMPLEMENTATION <name> { <object_descriptions> }; N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D System Configuration All objects within Implementation Definition part are described using the same syntax. <object_type> { <property_definitions> }; Object type is defined by the object keyword. For Motorola OSEK OS implementation the following object types are implemented: OS, TASK, ISR, STACK, RESOURCE, EVENT, COUNTER, ALARM, MESSAGE The set of object properties are to be defined within the object description. Both implementation specific attribute and reference shall be defined before it is used. The attribute definition has the following structure: User's Manual 136 OSEK Operating System -- Rev 1.2 System Configuration MOTOROLA The WITH_AUTO specifier can be combined with any type. If WITH_AUTO can be specified it means that this attribute can have the value AUTO and the possibility of automatic assignment. Data types defined for OIL are listed below. Note that these data types are not necessarily the same as the corresponding C data types. * INT - Any integer number. * ENUM - The list of possible values shall be presented. Any value from the list can be assigned to this attribute. * BOOLEAN - The attribute of this type can have either TRUE or FALSE value. * STRING - Any 8-bit character sequence enclosed in doublequotes, but not containing double-quotes can be assigned to this attribute. If the `\' symbol is placed before the EOL symbol (EndOf-Line) in the string then the next line is the continuation of the previous one. This is identical to the same rule for long text strings in the C language. A reference is a special type of value intended to define links between system objects. The reference definition has the following structure: <object_type> <reference_name> [ <multiple_specifier> ]; The reference type is taken from the referenced object (e.g. a reference to a task shall use the TASK keyword as reference type). A reference can `point to' any system object. Multiple reference is the possibility to refer to several objects of the same type with one OIL statement. For example the task can refer to several events. If the reference shall be defined as a 'multiple' reference then the '[]' brackets shall be present after the reference name. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Configuration 137 A G R E E M E N T The attribute type and attribute value range (if it exists) shall be defined. The range of attribute values can be defined in two ways: either the minimum and maximum allowed attribute values are defined (the [0..12] style) or the list of possible attribute values are presented (like C enumeration type). N O N - D I S C L O S U R E <attr_type> [ WITH_AUTO ] [ <attr_range> ] <attr_name> [ = <default_value> ] ; R E Q U I R E D System Configuration OIL Concept 12.4.5 Application Definition In the application definition the OSEK application is composed from a set of system objects. In general the application can contain more than one system object of the same type. Since an application is performed on CPU the entity called CPU is introduced as the top of the description. This entity encompasses all local objects such as tasks, messages, etc. Therefore, CPU can be considered as a container for application objects. This concept is introduced to provide future OIL evolution towards to distributed system support. This entity is identified by the keyword CPU. 12.4.5.1 Object Definition All objects are described using the same syntax. <object_type> <object_name> { <property_definitions> }; Objects are labeled by keywords which shall be written in upper case. Object attributes and references are also labeled by the keywords. The keywords are introduced in Section 13 System Objects Definition. After an object keyword the object name must follow. Name is combined from any symbols up to 32 symbols long. N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D System Configuration A set of attributes and references belonging to an object is enclosed in curly brackets, like in C language. All assignments are made via the `=' operator. Each statement ends with semicolon - `;' like in the C language. A reference is represented as a reference type keyword assigned with a name of the object referenced. If multiple reference pointed to the set of object the object names are listed via comma inside the curly brackets, for example task referencing to own events: EVENT = { MyEvent1, MyEvent2}; User's Manual 138 OSEK Operating System -- Rev 1.2 System Configuration MOTOROLA #include <filename.oil> #include "[path]filename.oil" The filename can be optionally preceded by a directory specification. The quoted form means that a header file is being looked for in the current directory first, then along the path specified by the "/I" commandline option, then along paths specified by the special environment variable. The angle-bracket form means that a header file is being looked for first along the path specified by the "/I" command-line option, then along paths specified by the special environment variable. 12.4.5.3 Comments An OIL file may contain comments. The '/*' and '//' characters define the start of a comment. Any characters after '//' are considered as a comment and the end of line (EOL) terminates the comment. Any characters after '/*' are considered as comments and the end of the comment is defined by '*/'. Nested comments are not allowed in OIL. 12.4.5.4 File Structure Any file in the Standard OIL format describes an application for a single CPU and, in general, must have the following structure: OIL_VERSION = <version>; IMPLEMENTATION <name> { // Implementation definition <OBJECT_TYPE> { ...list of implementation specific object attributes... }; ... }; CPU <name> { // Definition of the application on CPU <OBJECT_TYPE> <object_name> { // System object definition <ATTRIBUTE> = <value>; <REFERENCE> = <object_name>; <REFERENCE> = { <object_name>, ... }; ... list of object attributes and references ... OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Configuration 139 A G R E E M E N T The preprocessing directive to include other OIL files is allowed in any place of the OIL file. This statement has the same syntax as in ANSI-C: N O N - D I S C L O S U R E 12.4.5.2 Include Directive R E Q U I R E D System Configuration OIL Concept }; ... list of objects ... } 12.4.6 Configuration File Rules The application configuration files must conform some simple rules to be successfully processed. The rules are: * Each object has the unique name; * An object can have a set of attributes which define object properties; * An object can have a set of references to other system objects; * Each object shall be described only once, any type of redefinitions is not allowed; * All statements must be written without errors; * It is recommended to avoid conflicting statements (e.g., the system property TaskOwnStack is not set, but the own task stack is defined for a task) since it leads to error or warning messages. N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D System Configuration User's Manual 140 OSEK Operating System -- Rev 1.2 System Configuration MOTOROLA 13.1 Contents 13.2 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .141 13.3 OS Definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .142 13.4 Task Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .156 13.5 Stack Definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .159 13.6 Resource Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160 13.7 Event Definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .161 13.8 Counter Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .161 13.9 Alarm Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .163 13.10 Message Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .164 R E Q U I R E D Section 13. System Objects Definition A G R E E M E N T User's Manual -- OSEK Operating System 13.12 Different Application Modes Definition . . . . . . . . . . . . . . . . . .168 13.2 General All objects that are controlled by the Operating System - tasks, resources, alarms, messages, counters, ISRs and even the OS itself are considered as system objects. Each of them has its unique characteristics defined by the user. To specify parameters for each system object the special statements are used for each object. All statements are described below in detail. Some parameters represents memory addresses. They are defined either automatically or by the user. If the user does not need to control memory address such parameters should be omitted in definition statements. In this case SG automatically creates the code to allocate OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Objects Definition 141 N O N - D I S C L O S U R E 13.11 ISR Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .167 N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D System Objects Definition memory areas. If the user explicitly specifies the address then the symbolic name (e.g. MyTaskStack) should be provided in the corresponded position. This name must be defined in a user's file (e.g. an array can be defined for memory area) and declared as external name before the generated source files will be used. Such techniques is demonstrated in sample application, see Apppendix A Sample Application. 13.3 OS Definition Description: The object Operating System is the mandatory one for any application. It defines OS and its properties for the application. The keyword OS is used for this object type. See Section 3 Operating System Architecture for more detailed information about OS. The sample of Operating System definition is: OS sampleOS { CC = BCC2; STATUS = STANDARD; }; Below the list of all additional attributes which can be defined for an object of the OS type follows. Brief explanations are provided. This list is divided into parts which correspond to appropriate system objects. 13.3.1 Global System Attributes This group of attributes represents system features which are common for the whole system. * OSVERSION (ENUM) Defines the version of OSEK OS specification which OS supports. This attribute can have values 1 or 2. In the current OSEK OS implementation it is necessary to specify 2 as OSVERSION value. * TargetMCU (ENUM) Specifies the CPU type. Possible values are HC08, HC12, CPU32, MPC, MCORE and WINNT. User's Manual 142 OSEK Operating System -- Rev 1.2 System Objects Definition MOTOROLA * ORTIRunningTask (BOOLEAN) Specifies that the running task identification in run-time support will be used. This attribute will be ignored if DEBUG_LEVEL = 0 (see Section 18 ORTI Implementation for the details). * ORTICurrentService (BOOLEAN) Specifies that the OSEK OS system calls identification in run-time support will be used. This attribute will be ignored if DEBUG_LEVEL = 0 (see Section 18 ORTI Implementation for the details). * HCBasePage (BOOLEAN) Defines that the base memory page will be used for system variables. This option may reduce the OS code size by means of the direct addressing mode usage when possible. This is a target specific attribute. * HCBankCode (BOOLEAN) Specifies that the banked memory model support will be used. This is a target specific attribute. Defines that memory bank switching is supported by the system. * HCAltRegISR (BOOLEAN) This attribute is only applicable if TargetMCU is MCORE. It specifies that Alternative Register File will be used for ISR processing. * CC (ENUM) The CC attribute specifies the Conformance Class which is supported by the OS. This attribute has the type ENUM. The possible values are the following: - BCC1 - BCC2 - ECC1 OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Objects Definition 143 A G R E E M E N T DEBUG_LEVEL (ENUM) Specifies the ORTI support in OS. The attribute can have values 0 or 1. If the system has the DEBUG_LEVEL = 0 the static ORTI support is switched off. If the system has the DEBUG_LEVEL = 1 this mode is considererd to be a debudding mode (see Section 18 ORTI Implementation for the details). N O N - D I S C L O S U R E * R E Q U I R E D System Objects Definition OS Definition R E Q U I R E D System Objects Definition - ECC2 - AUTO A G R E E M E N T * STATUS (ENUM) The STATUS attribute specifies the debugging ability of OS. If the system has the EXTENDED status some additional checks are performed to detect run-time errors. This mode is considered to be a debugging mode. Standard status OS performs only very limited set of checks, the performance is increased and the amount of consumed memory is decreased. This attribute has the type ENUM. The possible values are the following: - STANDARD N O N - D I S C L O S U R E - EXTENDED * SimpleScheduler (BOOLEAN) If the attribute is TRUE the simplified scheduler will be used in the system, if each task has an unique priority and task multiply activation mechanism is not used. It reduces the OS code and increases system performance. * UseMainStack (BOOLEAN) If the attribute is TRUE the same stack area is used for the main() function (during start-up), for the scheduler stack and for the ISR stack, e.g. the effective top of stack is the top of stack when OS startup is called within main(). Therefore, user should avoid using of local variables in main() to keep top of stack as high as possible. * HCLowPower (BOOLEAN) If the attribute is TRUE an instruction that puts CPU in low power mode is used instead of the scheduler's idle loop. * HCLowPowerMode (ENUM) This attribute defines LowPowerMode which will be used by the scheduler (for some targets) (see Section 15 HC12 PlatformSpecific Features for more information). User's Manual 144 OSEK Operating System -- Rev 1.2 System Objects Definition MOTOROLA * InterruptMaskControl (BOOLEAN) If the attribute is FALSE (while the EntryExitISR attribute is TRUE) interrupt masks are not controlled by the operating system. Services EnableInterrupt, DisableInterrupt, GetInterruptDescriptor are not supported. * NodeNumber (INT) The attribute of the type INT specifies the maximum number of tasks in the non-suspended state, available in the system. In fact, this parameter specifies the number of task control blocks, allocated in the system. * SchedStackSize (INT) The attribute of the type INT specifies the size (in bytes) of the scheduler's idle loop stack. It should not be less than the interrupt stack frame. If the system property UseMainStack is set this attribute (and SchedStackAddress also) is ignored. * SchedStackAddress (STRING) The attribute of the type STRING specifies the bottom of the scheduler stack. This address can be defined explicitly to provide a way to optimize stack allocation. In this case it is presented as an array of characters named by SchedStackAddress attribute value. This array should be defined in a user's source file and declared in a user's header which is to be included into the system configuration source file (see Section 14.3.2 Source Files). * MaxPrio (INT) The attribute of the type INT specifies the number of task priorities in the system. This parameter is ignored if the attribute SimpleScheduler is TRUE, since in this case it must be equal to the number of tasks. * NodeStackSize (INT) The attribute of the type INT specifies the size of the stack (in bytes) per each task node. The total size of the memory area for OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Objects Definition 145 A G R E E M E N T EntryExitISR (BOOLEAN) If the attribute is FALSE it is assumed that there are no interrupt service routines in the system at all and the Operating System does not have any interrupt handling mechanisms. Interrupt management services are not supported. N O N - D I S C L O S U R E * R E Q U I R E D System Objects Definition OS Definition R E Q U I R E D System Objects Definition N O N - D I S C L O S U R E A G R E E M E N T task nodes' stacks is defined as multiplication of this parameter by the NodeNumber value. This parameter is ignored if the attribute NodeStack is FALSE. * NodeStackAddress (STRING) The attribute of the type STRING specifies the bottom of task nodes' stacks. This address can be defined explicitly to provide a way to optimize stacks allocation. In this case it is presented as an array of characters named by NodeStackAddress attribute value. This array should be defined in a user's source file and declared in a user's header which is to be included into the system configuration source file (see Section 14.3.2 Source Files). This parameter is ignored if the attribute NodeStack is FALSE. * UseCommonArea (BOOLEAN) This attribute, if turned TRUE, causes system to reduce stack usage for certain services (those ones requiring more stack space). This leads to static memory objects (`common area') using prior to stack space and could significantly reduce RAM space overhead (see Section 15 HC12 Platform-Specific Features for more information). * CopyrightNotice (BOOLEAN) The attribute specifies whether copyright notice should be incorporated into OS ROM code. * Reconfig (BOOLEAN) If the option is turned on, the number of different application modes (different sets of tasks) may be established in the same OSEK OS application (see Section 11.6 Application Modes). In this case it is possible to change application mode after system shutdown. If Reconfig option is set, then Extended OIL format should be used to define application modes. If it is not necessary to have a number of application modes in the same application, then it is recommended to turn this property off. It decreases the needed amount of RAM and increases execution speed. User's Manual 146 OSEK Operating System -- Rev 1.2 System Objects Definition MOTOROLA * UseMoveBlockInstruction (BOOLEAN) Defines whether OS has to use CPU memory move block instructions or not. This attribute is intended for MPC only. 13.3.2 Task Related Attributes This group of attributes controls task features. * SCHEDULE (ENUM) The SCHEDULE attribute specifies the kinds of scheduling which are supported by the OS. This attribute allows for a cross-check of the requirements of the tasks and the capabilities offered by the operating system. The possibility of automatic assignment for this attribute is supported. The possible values are the following: - NON - FULL - MIXED - AUTO * MultiplyActivation (BOOLEAN) The attribute controls the multiply activation ability for Conformance Classes. If the attribute is FALSE multiply activation is disabled for tasks. * TaskIndexMethod (BOOLEAN) If the attribute is TRUE then the intermediate vector of the pointers to tasks control blocks is used (fast and deterministic access to task nodes). * NodeStack (BOOLEAN) The attribute defines the presence of task node stacks in the system. If it is FALSE there are no task node stacks implemented. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Objects Definition 147 A G R E E M E N T ExtendedContext (BOOLEAN) Defines whether OS has to support task context extension or not. Valid only if the target MCU has the corresponding hardware support (MPC505) or it is necessary due to specific compiler behavior (HC08). N O N - D I S C L O S U R E * R E Q U I R E D System Objects Definition OS Definition N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D System Objects Definition * StackPool (BOOLEAN) The attribute defines the presence of stack pools in the system. If it is FALSE there are no stack pools implemented. * PersistentNode (BOOLEAN) If the attribute is TRUE a persistent task control block may be assigned to the task. * PersistentStack (BOOLEAN) If the attribute is TRUE a persistent stack buffer may be assigned to the task. * TaskOwnStack (BOOLEAN) The attribute defines that a task may have its own stack. * UseSameContext (BOOLEAN) If the attribute is TRUE the same run time context frame is used both for non-preemptive and preemptive tasks in mixedpreemptive systems. * TaskBasePage (BOOLEAN) If the attribute is TRUE, the task control blocks are placed into the base page memory. It increases the system performance since CPU accesses the base page faster than extended memory. In this case the user is responsible for the needed amount of RAM in the base page for the desired number of task nodes. * ChainTaskItself (BOOLEAN) The attribute can be set as FALSE if no tasks that chain itself. It decreases the task control block size. * NonPreemptCtxRegNum (INT) The attribute specifies the number of extended registers to be included into non-preemptive task context. It should contain value from 1 till 18. Intended for MPC505 only. Valid only if ExtendedContext = TRUE. * SaveNonPreemptCtxExt (STRING) The attribute specifies the assembler macro for saving extended registers into non-preemptive task context. It should be a STRING which contains inline assembler statements for saving extended registers. Intended for MPC505 only. Valid only if ExtendedContext = TRUE. User's Manual 148 OSEK Operating System -- Rev 1.2 System Objects Definition MOTOROLA * PreemptCtxRegNum (INT) The attribute specifies the number of extended registers to be included into preemptive task context. It should contain value from 1 till 18. Intended for MPC505 only. Valid only if ExtendedContext = TRUE. * SavePreemptCtxExt (STRING) The attribute specifies the assembler macro for saving extended registers into preemptive task context. It should be a STRING which contains inline assembler statements for saving extended registers. Intended for MPC505 only. Valid only if ExtendedContext = TRUE. * RestorePreemptCtxExt (STRING) The attribute specifies the assembler macro for restoring extended registers from preemptive task context. It should be a STRING which contains inline assembler statements for restoring extended registers. Intended for MPC505 only. Valid only if ExtendedContext = TRUE. 13.3.3 Interrupt Related Properties This group of attributes defines parameters of ISR execution. * IsrStackSize (INT) The attribute of the type INT specifies the size (in bytes) of the ISR stack. If the attribute UseMainStack is TRUE this attribute (and ISRStackAddress also) can be omitted. * IsrStackAddress (STRING) The attribute of the type STRING specifies the bottom of the ISR stack. This address can be defined explicitly to provide a way to optimize stack allocation. In this case it is presented as an array of characters named by IsrStackAddress attribute value. This array OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Objects Definition 149 A G R E E M E N T RestoreNonPreemptCtxExt (STRING) The attribute specifies the assembler macro for restoring extended registers from non-preemptive task context. It should be a STRING which contains inline assembler statements for restoring extended registers. Intended for MPC505 only. Valid only if ExtendedContext = TRUE. N O N - D I S C L O S U R E * R E Q U I R E D System Objects Definition OS Definition R E Q U I R E D System Objects Definition N O N - D I S C L O S U R E A G R E E M E N T should be defined in a user's source file and declared in a user's header which is to be included into the system configuration source file (see Section 14.3.2 Source Files). * DisableInterruptMask (INT) The attribute of the type INT specifies the value of the interrupt mask, which corresponds to all interrupts disabled. * EnableInterruptMask (INT) The attribute of the type INT specifies the value of the interrupt mask, which corresponds to all interrupts enabled. * TaskLevelMask (INT) The attribute of the type INT specifies the value of the interrupt mask, which, typically, corresponds to the middle level of enabled interrupts in the system. * InitialMask (INT) The attribute of the type INT specifies the value of the interrupt mask, which, typically, corresponds to the initial level of enabled interrupts during the system startup. * ISRCategory1 (BOOLEAN) The attribute specifies whether the ISR of category 1 is supported by OS or not. Currently this attribute does not affect OS code. * ISRCategory2 (BOOLEAN) The attribute specifies whether the ISR of category 2 is supported by OS or not. Currently this attribute does not affect OS code. * ISRCategory3 (BOOLEAN) The attribute specifies whether the ISR of category 3 is supported by OS or not. * ISRCtxRegNum (INT) The attribute specifies the number of extended registers to be saved into ISR stack frame. It should contain value from 1 till 18. Intended for MPC505 only, not implemented yet. Valid only if ExtendedContext = TRUE. * SaveISRCtxExt (STRING) The attribute specifies the assembler macro for saving extended registers into ISR stack frame. It should be a STRING which User's Manual 150 OSEK Operating System -- Rev 1.2 System Objects Definition MOTOROLA RestoreISRCtxExt (STRING) The attribute specifies the assembler macro for restoring extended registers from ISR stack frame. It should be a STRING which contains inline assembler statements for restoring extended registers. Intended for MPC505 only, not implemented yet. Valid only if ExtendedContext = TRUE. * UnorderedExceptions (BOOLEAN) The attribute allows handling of unordered exceptions. Intended for MPC only. 13.3.4 Resources and Events Related Attributes The attributes control resources and events. * Resources (BOOLEAN) This attribute defines whether resource management is provided by OS or not. * FastResource (BOOLEAN) The attribute can be specified by the user to increase the system performance. If it is TRUE the system will work faster. But this attribute may be used only for debugged applications, because errors related to incorrect access and priority are not signalled. If this attribute is TRUE less amount of ROM and RAM is needed for resources. But, if resource priorities have a big difference (e.g. first resource has priority 1 and the second resource has priority 20) this attribute does not lead to RAM saving. * ResourceAccessCheck (BOOLEAN) Defines whether E_OS_ACCESS error code is returned by GetResource service or not. If it is TRUE, then error code will be returned in EXTENDED status based on task definition in OIL-file. If the system has STANDARD status or FastResource property turned on or more than 8 resources (including Scheduler) are defined in application, then this attribute should be set to FALSE. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Objects Definition 151 A G R E E M E N T * N O N - D I S C L O S U R E contains inline assembler statements for saving extended registers. Intended for MPC505 only, not implemented yet. Valid only if ExtendedContext = TRUE. R E Q U I R E D System Objects Definition OS Definition * Events (BOOLEAN) This attribute defines whether event management is provided by OS or not. 13.3.5 Counters and Alarms Related Attributes This group of attributes controls counters and alarms features. N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D System Objects Definition * Counters (BOOLEAN) This attribute defines whether counters are provided by OS or not. * CounterSize (ENUM) This attribute defines the size of all counters. The valid values are 8, 16 and 32 which conform to byte, word and long word size of counters. * Alarms (BOOLEAN) This attribute defines whether alarms are provided by OS or not. * AlarmList (BOOLEAN) If the attribute is TRUE the running alarms are linked into a list which decreases the time for alarm handling. * AlarmDeltaList (BOOLEAN) If the option is turned on the running alarms are linked into ordered alarm delta-list which significantly decreases the time for CounterTrigger service if too much alarms are connected with the same counter (more than 10). The time for alarm management services like SetAbsAlarm, SetRelAlarm, GetAlarm will be increased. * CyclicAlarm (BOOLEAN) If the option is turned on, the cyclic alarms are supported. Otherwise, no one alarm may be cyclic, which decreases RAM usage for alarm control blocks, as well as decreases code usage and advances timing of alarms services. This option is turned on by default. User's Manual 152 OSEK Operating System -- Rev 1.2 System Objects Definition MOTOROLA * TimerHardware (ENUM) This attribute is intended to select the hardware interrupt source for the system counter (among the accessible MCU devices). See Section 15 HC12 Platform-Specific Features and Apppendix E Quick Reference for details about possible meanings of these parameters. * SysTimer (BOOLEAN), Prescaler (BOOLEAN), PrescalerValue (INT), TimerModulo (BOOLEAN), TimerModuloValue (INT) The set of parameters to tune the selected hardware interrupt source is introduced: SysTimer, Prescaler, PrescalerValue, TimerModulo, TimerModuloValue. One or more parameters can be here in accordance with the hardware features. For more details see Section 15 HC12 Platform-Specific Features. This parameter(s) can be omitted. 13.3.6 Messages Related Attributes These are additional attributes to control local messages. * UnqueuedMessages (BOOLEAN) The attribute allows Unqueued Messages in the system. * UnqueuedMsgDefaultValue (BOOLEAN) The attribute allows Unqueued Messages to have default values. * QueuedMessages (BOOLEAN) The attribute allows Queued Messages in the system. * QueuedMsgOneToN (BOOLEAN) If the attribute is TRUE, 1:N Queued Messages are allowed. * ActivateOnMsg (BOOLEAN) If the attribute is TRUE task activation on message arrival is supported. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Objects Definition 153 A G R E E M E N T MinAlarmRAM (BOOLEAN) If the option is turned on, the alarm handling is optimized for memory (RAM). Otherwise, alarm handling is optimized for speed. When turned on, the alarm control block is significantly decreased, especially when AlarmList option is turned off. N O N - D I S C L O S U R E * R E Q U I R E D System Objects Definition OS Definition * AlarmOnMsg (BOOLEAN) If the attribute is TRUE an alarm can be linked to message arrival. * SetEventOnMsg (BOOLEAN) If the attribute is TRUE event setting is allowed on message arrival. 13.3.7 Hook Routines Related Attributes These attributes define hook routines support in the system. N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D System Objects Definition * ErrorHook (BOOLEAN) If the attribute is TRUE the user's hook for error handling is supported by the system (the ErrorHook hook routine). * PreTaskHook (BOOLEAN) If the attribute is TRUE the user's hook for context switching is supported by the system (the PreTaskHook hook routine). * PostTaskHook (BOOLEAN) If the attribute is TRUE the user's hook for context switching is supported by the system (the PostTaskHook hook routine). * StartupHook (BOOLEAN) If the attribute is TRUE the user's hook is called by the system at the end of the system initialization (the StartupHook hook routine). * ShutdownHook (BOOLEAN) If the attribute is TRUE the user's hook is called by the system when the OS service ShutdownOS has been called (the ShutdownHook hook routine). * IdleLoopHook (BOOLEAN) If the attribute is TRUE the user's hook to be called from scheduler idle loop is supported by the system (the IdleLoopHook hook routine). * InternalErrorHandler (BOOLEAN) The attribute defines whether the internal error handler is implemented. User's Manual 154 OSEK Operating System -- Rev 1.2 System Objects Definition MOTOROLA UserCommand1 (STRING) The attribute defines entry point of the user's hook #1 to be called from the OS Dispatcher thread (for OS/NT with interrupt emulation only). * UserCommand2 (STRING) The attribute defines entry point of the user's hook #2 to be called from the OS Dispatcher thread (for OS/NT with interrupt emulation only). * UserCommand3 (STRING) The attribute defines entry point of the user's hook #3 to be called from the OS Dispatcher thread (for OS/NT with interrupt emulation only). 13.3.8 OS Service Related Attributes * Task management services: ActivateTask, TerminateTask,ChainTask, ChainTaskItself, Schedule, GetTaskId, GetTaskState, GetTCBInfo * Resource management services: GetResource, ReleaseResource * Event management services: SetEvent, ClearEvent, GetEvent, WaitEvent * ISR management services: EnterISR, LeaveISR, EnableInterrupt, DisableInterrupt, GetInterruptDecsriptor * Counter related services: InitCounter, CounterTrigger, AdvanceCounter, GetCounterValue, GetCounterInfo OSEK Operating System -- Rev 1.2 MOTOROLA N O N - D I S C L O S U R E The group of attributes is designed to exclude particular OS services. All these attributes has the BOOLEAN type. If an attribute is FALSE the corresponded service is excluded from the OS code. Names of these attributes are the same as corresponding OS service names. E.g., if the attribute InitCounter is set as FALSE it means that this service will be unavailable in an application. This is the list of such attributes: User's Manual System Objects Definition A G R E E M E N T * R E Q U I R E D System Objects Definition OS Definition 155 N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D System Objects Definition * Alarm related services: SetRelAlarm, SetAbsAlarm,CancelAlarm, GetAlarm, GetAlarmBase * Communication services: SendMessage, ReceiveMessage, GetMessageResource, ReleaseMessageResource, GetMessageStatus * Execution control: GetActiveApplicationMode, ShutdownOS 13.4 Task Definition Description: This statement is used to define task data. Several statements can be in the configuration file, each statement defines one task. This object presents a task. Attributes of this object type define task properties. Links with other system objects are defined via references. The keyword TASK is used for this object type. See Section 4 Task Management for more detailed information about OSEK tasks. The sample of a task definition is: TASK TaskA { TYPE = EXTENDED; PRIORITY = 2; SCHEDULE = NON; ACTIVATION = 5; STACKSIZE = 64; AUTOSTART = TRUE; EVENTS = { event1, event2, event3 }; }; 13.4.1 Object Attributes The object has the following attributes: * TYPE (ENUM) This attribute has the type ENUM. The OSEK task may be one of the following types: - BASIC User's Manual 156 OSEK Operating System -- Rev 1.2 System Objects Definition MOTOROLA PRIORITY (INT) The priority of the task is defined by the value of the PRIORITY attribute. The bigger value of the PRIORITY attribute corresponds to the higher priority. This attribute has the INT type. The default value range is from 0 to 255. * SCHEDULE (ENUM) The run-time behavior of the task is defined by this attribute. If the task may be preempted by another one at any point of execution - this task attribute shall have the FULL value (preemptive task). If the task can be preempted only at specific points of execution (explicit rescheduling points) the attribute shall have the NON value (non-preemptive task). This attribute has the type ENUM with the values: - FULL - NON * ACTIVATION (INT) The maximum number of registered activation requests for the task. This attribute has the INT type. The default value range is from 1 to 255. The maximum number can be constrained in the implementation specific definition part. The value 1 means that a task cannot be multiple activated, only single activation is allowed. * STACKSIZE (INT) This attribute defines the size of the task stack. It depends on the CPU family and functionality of the task. The attribute has the type INT. No default value range is defined. The maximum stack size can be constrained by the implementation. * AUTOSTART (BOOLEAN) This attribute determines whether the task is activated during the system start-up procedure or not. It has the BOOLEAN type, so the possible values are TRUE and FALSE. * StackMethod (ENUM) This attribute specifies the stack allocation method. The attribute (the ENUM type) has three available values. NODESTACK means that task node stack is implicitly assigned to be used by the task (during the task activation). POOLSTACK means that a stack OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Objects Definition 157 A G R E E M E N T * N O N - D I S C L O S U R E - EXTENDED R E Q U I R E D System Objects Definition Task Definition R E Q U I R E D System Objects Definition N O N - D I S C L O S U R E A G R E E M E N T should be dynamically allocated to the task from the stack pool during task activation. OWNSTACK (the default attribute value) means that a stack is explicitly assigned to the task (in this case the address of the top of the stack will be calculated by the system generation utility). Note that to get a correct OIL file the value must correspond to the appropriate OS attribute (NodeStack, StackPool and TaskOwnStack). * StackAddress (STRING) The attribute of the type STRING specifies the bottom of the task stack. This address can be defined explicitly to provide a way to optimize stack allocation. In this case it is presented as an array of characters named by StackAddress attribute value. This array should be defined in a user's source file and declared in a user's header which is to be included into the system configuration source file (see Section 14.3.2 Source Files). * MemoryBank (INT) The attribute (INT type) defines the memory bank for the task code. * InterruptMask (INT) The attribute (INT type) defines the starting task's interrupt mask. If this parameter is omitted, then the value of the TaskLevelMask attribute is used * PersistentNode (BOOLEAN) If the attribute is TRUE a persistent task node is assigned to the task. * PersistentStack (BOOLEAN) If the attribute is TRUE a persistent stack buffer is assigned to the task. 13.4.2 Object References A task in OSEK OS has the set of allowed references. A reference is presented as the symbolic name of an object that is referenced to by the task. The following references are allowed: User's Manual 158 OSEK Operating System -- Rev 1.2 System Objects Definition MOTOROLA * EVENT (multiple) An extended task can have a set of events. These events can be cleared and waited for by the task. All task events shall be pointed to define the event mask in case of auto-assignment (see section Section 13.7 Event Definition). * MESSAGESENT (multiple) If a task sends a message (has write access to a message) this message shall be specified as the reference. The symbolic name of the message shall be pointed. * MESSAGERECEIVED (multiple) If a task receives a message (has read access to a message) this message shall be specified as the reference. The symbolic name of the message shall be pointed. It is not mandatory to reference messages which are sent or received by the task. But it is recommended to do to simplify application consistency verification and to eliminate possible errors, especially in case of 1:N communication. * NOTE: StackPool (single) If a task uses the stack from a stack pool the reference to the dedicated stack pool must be provided. The symbolic name of the stack pool shall be pointed. If a task uses a stack from the stack pool the value of the task attribute STACKSIZE is ignored. 13.5 Stack Definition Description: This statement is used to define stack pool data. Several statements can be in the configuration file, each statement defines one pool. The keyword for this object is STACK. See Section 4.7.4 Task Stack for OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Objects Definition 159 A G R E E M E N T RESOURCE (multiple) If the task accesses a resource at run-time this resource shall be pointed. The resource Ceiling priority is calculated as the highest priority of tasks accessing this resource (or higher one). N O N - D I S C L O S U R E NOTE: * R E Q U I R E D System Objects Definition Stack Definition R E Q U I R E D System Objects Definition more information about the task stack. The sample of a stack definition is: STACK StackTaskA { StackSize = 128; NumberOfStacks = 5; StackAreaAddress = 0x400; }; N O N - D I S C L O S U R E A G R E E M E N T 13.5.1 Object Attributes The attributes of the STACK object reflect these physical parameters of a pool. They are: * StackSize (INT) The attribute represents the size of a stack buffer, it has the type INT. * NumberOfStacks (INT) The attribute corresponds the number of buffers in the pool, it also has the type INT. * StackAreaAddress (STRING) The attribute specifies the start address of the pool memory area and it has the type STRING. This optional parameter serves for explicit memory allocation for the task stack pool. 13.6 Resource Definition Description: This object is intended for the resource management. The resource object has no standard attributes and references. The resource Ceiling priority is calculated automatically on the basis of information about priorities of tasks using the resource. The keyword RESOURCE is used for this object type. Section Section 7 Resource Management describes resource concept in OSEK. The sample of a resource definition is: RESOURCE ResAccess { }; User's Manual 160 OSEK Operating System -- Rev 1.2 System Objects Definition MOTOROLA * PRIORITY (INT) The priority of the resource is defined by the value of the PRIORITY attribute. The bigger value of the PRIORITY attribute corresponds to the higher priority. This attribute has the INT type. This attribute has the possibility of automatically assignment. In this case the resource Ceiling priority is calculated automatically on the basis of information about priorities of tasks using the resource. 13.7 Event Definition Description: This object is intended for the event management. The event object has no references. The keyword EVENT is used for this object type. Section Section 9 Events describes events in OSEK. The sample of an event definition is: EVENT event1 { MASK = 0x01; }; 13.7.1 Object Attributes * MASK (INT) The event is represented by its mask. The attribute has the type INT. The event mask is the number which range can be defined in the implementation specific definition part. The other way to assign event mask is to declare it as AUTO. In this case event masks will be assigned automatically according to their distribution among the tasks. 13.8 Counter Definition Description: OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Objects Definition 161 A G R E E M E N T The object has the following attributes: N O N - D I S C L O S U R E 13.6.1 Object Attributes R E Q U I R E D System Objects Definition Event Definition This object presents OSEK Operating system counters. Attributes of this object type define counter properties. A counter has no references, it is referenced to by other object. The keyword COUNTER is used for this object type. OSEK counters are described in section Section 8.3 Counters. The sample of a counter definition is: COUNTER Timer { MINCYCLE = 16; MAXALLOWEDVALUE = 128; TICKSPERBASE = 90; }; 13.8.1 Object Attributes The object has the following standard attributes: N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D System Objects Definition * MAXALLOWEDVALUE (INT) The attribute defines the maximum allowed counter value. When the counter reaches this value it rolls over and starts count again from zero. The attribute has the type INT. * MINCYCLE (INT) The attribute specifies the minimum allowed number of counter ticks for a cyclic alarm linked to the counter. (In fact, this parameter has a sense only for systems with extended OS status since it is checked in this case only.) The attribute has the type INT. * TICKSPERBASE (INT) For the system timer (if specified) this is the number of ticks that are required to reach 10 milliseconds. This value cannot be derived automatically from other counter related attributes (see also PrescalerValue, TimerModuloValue Section 13.3.5 Counters and Alarms Related Attributes). For the rest counters this attribute specifies the number of ticks required to reach a counter-specific value (the interpretation is up to the user). The attribute has the type INT. * TICKDURATION (INT) For the system timer (if specified) this is the duration of a tick in nanoseconds. The attribute has the type INT. User's Manual 162 OSEK Operating System -- Rev 1.2 System Objects Definition MOTOROLA SystemTimer (BOOLEAN) This attribute specifies whether the counter is the system timer. By default this attribute has the value FALSE. Note, however, that only one counter must be defined as the system timer. 13.9 Alarm Definition Description: This object presents OS alarms. An alarm has no standard attributes. Links with other system objects are defined via references. The referenced counter and task must be already defined.The keyword ALARM is used for this object type. See section Section 8.4 Alarms for information about alarms. The sample of an alarm definition is: ALARM WakeTaskA { ACTION = SETEVENT; COUNTER = Timer; TASK = TaskA; EVENT = event1; }; A G R E E M E N T * R E Q U I R E D System Objects Definition Alarm Definition An alarm has the following allowed references: * ACTION (single) This attribute has the type ENUM. The ACTION may be one of the following types: - ACTIVATETASK - SETEVENT * COUNTER (single) An alarm shall be assigned to a particular counter to have an ability to operate. * TASK (single) The reference points to a task which is to be notified via activation or event setting when the alarm expires. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Objects Definition 163 N O N - D I S C L O S U R E 13.9.1 Object References * N O N - D I S C L O S U R E EVENT (single) An event which is to be set when the alarm expires is pointed here. The event is considered as an inseparable pair of the task and the event belonging to this task, so the reference to the task which owns the events shall be also defined for this alarm. 13.10 Message Definition Description: A G R E E M E N T R E Q U I R E D System Objects Definition This object is intended to present either a Unqueued or an Queued message. Attributes of this object type define message properties. Links with other system objects are defined via references. The keyword MESSAGE is used for this object type. Messages concept is described in section Section 10 Communication. The sample of a message definition is: MESSAGE Msg4TaskA { TYPE = UNQUEUEDMESSAGE; ITEMTYPE = "int"; ITEMS = 1; ALARMRESETTIME = 20; ALARMRESET = DrvAlarm; ACTION = SETEVENT; TASK = TaskA; EVENT = event1; }; 13.10.1 Object Attributes The object has the following attributes: * ACTION (ENUM) This attribute has the type ENUM. The ACTION may be one of the following types: - ACTIVATETASK - SETEVENT - NONE User's Manual 164 OSEK Operating System -- Rev 1.2 System Objects Definition MOTOROLA * ITEMTYPE (STRING) The message item can have the own type which has to be any C data type. Any ANSI-C type specifier is allowed. It is the standard C type identifier - char, int, float, double with any type modifiers (signed, unsigned, short, long) and also structure or union specifier (starting struct or union), enum specifier (starting enum), typedef name (any valid C-language identifier) enclosed in the double quotas. To use an array of standard C-language type the user must define the new type via typedef operator. In case of user's defined data types or enumerations such definitions must be in the user's code before using files produced by SG * ITEMS (INT) The queued message can have more than one item. This attribute specifies the capacity of the FIFO queue, i.e. the number of message items into the FIFO queue. The unqueued message always has only one item. * ALARMRESETTIME (INT) Alarm can be assigned to a message which is restarted at message arrival (alarm restart will happen as a result of SendMessage service execution). The time period for this alarm is defined by this attribute. The units are ticks of the counter assigned for the alarm. * StartupAlarm (BOOLEAN) This attribute specifies whether the alarm referenced by the message must be restarted during system start-up. By default this attribute has the value FALSE, it means that the alarm is not restarted during start-up. Restarting of the alarm may be used to trap the loss of the first message. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Objects Definition 165 A G R E E M E N T TYPE (ENUM) In accordance with the OSEK specification there are two types of messages: Unqueued and Queued. The possible value of this attribute are the following: - UNQUEUEDMESSAGE - QUEUEDMESSAGE N O N - D I S C L O S U R E * R E Q U I R E D System Objects Definition Message Definition * DefaultValue (STRING) This attribute presents the address of the ROM-based variable, which holds the default value of the unqueued message. This variable must have the type <ITEMTYPE>, and must be located in the user's code. The parameter may be omitted.This attribute is intended for unqueued messages only. * ReceiverNum (INT) The attribute defines the number of local task-receivers of the message. If it has a value greater than 1, then it is assumed, that several tasks may receive a message item from the message queue. * WithCopy (BOOLEAN) The attribute defines that unqueued message is used with copy (TRUE) or without copy (FALSE). 13.10.2 Object References A message in OSEK OS has the set of allowed references. A reference is presented as the symbolic name of an object that is referenced to by the message. The following references are allowed (identified via keywords): N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D System Objects Definition * ALARMRESET (single) The reference points to an alarm which is to be restarted when the message arrives (alarm restart will happen as a result of SendMessage service execution). * TASK (single) The reference points to a task which is to be notified via activation or event setting when the message arrives. * EVENT (single) An event which is to be set when the alarm expires is pointed here. The event is considered as an inseparable pair of the task and the event belonging to this task, so the reference to the task which owns the events shall be also defined for this message. User's Manual 166 OSEK Operating System -- Rev 1.2 System Objects Definition MOTOROLA This object presents an Interrupt Service Routine. The keyword ISR is used for this object type. The sample of an Interrupt Service Routine definition is: ISR TimerISR{ CATEGORY = 2; } 13.11.1 Object Attributes This object has the following attributes: * CATEGORY (ENUM) Specifies category of the Interrupt Service Routine. Possible values are: 1, 2 or 3 (see Section 6.4 ISR Categories for Interrupt Service Routine Categories details). * TYPE (ENUM) This attribute is only valid if TargetMCU global system attribute is MCORE and HCAltRegISR global system attribute is TRUE. It chooses between Fast Interrupt exception and all other exceptions. The possible values of this attribute are the following: - FAST - NORMAL * MESSAGESENT (multiple) Only a message which is sent by ISR can be referenced. If ISR sends a message (has write access to a message) this one shall be specified as the reference. The symbolic name of the appropriate message object shall be pointed. 13.11.2 Object References OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Objects Definition 167 A G R E E M E N T Description: N O N - D I S C L O S U R E 13.11 ISR Definition R E Q U I R E D System Objects Definition ISR Definition 13.12 Different Application Modes Definition Description: It is possible to introduce different application modes inside one CPU container by means of additional container object named CFG (configuration). This object is introduced in Extended OIL format (see Section 12.4.3 Extended OIL Format). A set of CFG statements can be represented inside one CPU to establish different application modes. The CFG statement contains a set of objects. To define application mode it is necessary to collect application mode dependent tasks inside corresponding CFG statement. It is possible to share a task between different application modes. In this case it is necessary to include corresponding task definition into all affected CFG objects. The CFG statement has the syntax similar to CPU syntax. A G R E E M E N T R E Q U I R E D System Objects Definition All application modes should be enumerated in special CFGACTIVE statement located inside the scope of corresponding CPU. N O N - D I S C L O S U R E The following is the OIL example of CPU description with two application modes and five tasks. Task TC code is shared between application modes. OIL_VERSION = "2.0e"; INCLUDE "mot20.oil" CPU cpu1 { CFGACTIVE = { ModeA, ModeB }; /* Force SG to use Extended */ /* OIL format */ /* Two application modes */ /* "ModeA", "ModeB" are */ /* defined */ .... CFG ModeA { /* Application mode "ModeA" */ TASK TC { ... }; /* TC code is shared between both modes */ TASK TA1 { ... }; /* ModeA specific task TA1 */ TASK TA2 { ... }; /* ModeA specific task TA2 */ }; CFG ModeB { /* Application mode "ModeB" */ TASK TB1 { ... }; /* ModeB specific task TB1 */ TASK TC { ... }; /* TC code is shared between both modes */ TASK TB2 { ... }; /* ModeB specific task TB2 */ }; STACK POOL { ... }; /* Stack pool definition */ COUNTER Timer { ... };/* Counter definition */ User's Manual 168 OSEK Operating System -- Rev 1.2 System Objects Definition MOTOROLA ALARM Alarm { ... }; .... /* Alarm definition */ }; N O N - D I S C L O S U R E A G R E E M E N T A task may have different properties in different application modes. Only TASK statements may be used inside CFG object in case of application mode definition. See Section 17.9.5 Examples of Application Modes Usage for details regarding different application modes definition. R E Q U I R E D System Objects Definition Different Application Modes Definition OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Objects Definition 169 N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D System Objects Definition User's Manual 170 OSEK Operating System -- Rev 1.2 System Objects Definition MOTOROLA 14.2 Application Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .171 14.3 Action Sequence to Build an Application . . . . . . . . . . . . . . . .172 14.4 Sample Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .178 14.2 Application Structure An application developed on the OSEK Operating System basis has a defined structure. An application consists of the Operating System kernel and several user's tasks and ISRs, which interact with the kernel by means of system services and internal mechanisms. ISRs receive control from hardware interrupt sources via the vector table. Tasks are controlled by the scheduler. They may use all means for intertask communications granted by OSEK OS to pass data and synchronize each other. Tasks and ISRs are considered as system objects. Resources, Unqueued and Queued messages, counters, and alarms are also considered as system objects, because they are controlled by the Operating System. An application typically also has configuration tables for different system objects, stack buffer pools and other entities. To create an application, the user should develop the desired application structure with all necessary objects and define interactions between them. All global Operating System properties, system objects and their parameters are defined by the user statically and cannot be redefined at run time. Special application configuration file is designed to perform such definition and the special tool that processes this file. See Section 12 System Configuration. After processing, files with system OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Building of Application 171 R E Q U I R E D 14.1 Contents A G R E E M E N T Section 14. Building of Application N O N - D I S C L O S U R E User's Manual -- OSEK Operating System object descriptors are created automatically. These files provide the code for all required ROM and RAM structures, arrays, tables, variables, etc. for all system objects defined in the configuration file. Memory allocation is performed during start-up procedure. 14.3 Action Sequence to Build an Application To build an application using the OSEK Operating System the user should perform a set of actions. These actions are relatively simple since the most important requirement is a clear understanding of the application's algorithm. The actions include creating the application configuration file, processing this file by the System Generator, writing the user's source code, compiling all files and linking the application files together with the OSEK OS code. This process is shown in Figure 14-1. N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Building of Application User's Manual 172 OSEK Operating System -- Rev 1.2 Building of Application MOTOROLA User's source code System Generator A G R E E M E N T OSEK OS kernel Files produced by SG Compiler Linker Executable file - user defined files - files produced by SG - OSEK Operating System components - development software Figure 14-1. Application building process 14.3.1 Application Configuration Applications built using OSEK OS are configured statically via the special configuration file written in OIL. Section 12 System Configuration describes the structure of such file and Section 13 System Objects Definition describes all possible statements in detail. This configuration file defines system specific parameters as well as system objects. Such a file can have any extension and the extension ".oil" is suggested by default. The configuration file has to be processed by the special utility named System Generator (SG). This utility is delivered as one of the parts of the OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Building of Application 173 N O N - D I S C L O S U R E Application configuration file R E Q U I R E D Building of Application Action Sequence to Build an Application R E Q U I R E D Building of Application OSEK Operating System. This tool runs as a simple MS-DOS application and produces header and source files. The following command is used to run SG: sysgen [-options] oil_file The following command line options are intended to control SG: A G R E E M E N T Table 14-1. System Generator command line options N O N - D I S C L O S U R E Option Description Default value -c* Defines * as the data file name Input file name with ".c" extension -h* Defines the header file name Input file name with ".h" extension -i* Defines the path for include files No -n* Defines * as the name of CPU for which output files are generated First CPU in the file -o For supporting backward compatibility previous version of No SG utility which treats the lesser value as the higher priority -p* Defines the property file name "osprop.h" -t* Defines the pathname for property template file "osprop.tpl" -v For verification mode only. When this option is defined the generation is not performed No The location of the property template file can be pointed either in command line or via the SYSGEN_TEMPLATE environment variable. In addition to command line option the OSB_INCLUDE_DIR environment variable can be used to specify the set of directories to search for include files. The SG utility produces three types of standard C-language files which are to be compiled and linked together with OS kernel code and user's source code: 1. The header file which describes the current configuration of the operating system, in other words, system properties. This file contains the preprocessor directives #define and #undef. This file is used at compile time to build the OS kernel with the specified properties. The default filename is "osprop.h" but the user can User's Manual 174 OSEK Operating System -- Rev 1.2 Building of Application MOTOROLA 3. The source file which contains initialized data and memory allocation for system objects. This file is compiled with "osprop.h" and other header files and then linked together with other application and OS files. By default, System Generator uses the input file name for this output file with "c" extension. NOTE: As a rule, the user is not allowed to edit files produced by the System Generator. It may lead to data inconsistency, compilation errors or unpredictable application behavior. 14.3.2 Source Files OSEK Operating System is delivered to the user as a set of source files. Header and source files of the Operating System are located in the predefined directories after OSEK OS installation, as it is described in Section 2.5.2 Installation. Paths to these directories have to be provided by the user. The OS source code is compiled and linked together with other application's files. The header file "osprop.h" describing system properties defines which functionality will have the OS kernel in run time. This file must be included in all user's and OS' source files. Since the user can specify another name for this file the special macro OSPROPH is designed to substitute the name. The following code can be used in all user's files (it is used in all OS source files): #if !defined (OSPROPH) #include <osprop.h> #else /* !defined (OSPROPH) */ #include OSPROPH #endif /* !defined (OSPROPH) */ The compiler command line (see Section 14.3.3 Compiling and Linking) in this case should have the option like this: OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Building of Application 175 A G R E E M E N T 2. The header file which contains definitions of data types and constants, and external declarations of variables which are needed to describe system objects. This file is used to compile application files. By default, System Generator uses the input file name for this output file with ".h" extension. N O N - D I S C L O S U R E assign another name (see Section 14.3.2 Source Files). R E Q U I R E D Building of Application Action Sequence to Build an Application R E Q U I R E D Building of Application -dOSPROPH="<filename>". <filename> is the name of the file with system properties definitions. But the user is allowed to use some other method to include the property definition header file in his/her source code. A G R E E M E N T Among other files SG generates configuration C-file containing definitions and initialization of OSEK OS configuration data and corresponding header H-file. Configuration C-file is a separate module, however, in some particular OSEK OS configurations, it could contain references to user defined data and structures (e.g. user's message structure types). This requires a method to provide SG generated configuration C-file with such user defined types and data declarations. Thus SG generates the following code in configuration C-file: #if defined(APPTYPESH) #include APPTYPESH /* user's header file */ #endif /* defined(APPTYPESH) */ The compiler command line (see Section 14.3.3 Compiling and Linking) in this case should have the option like this: N O N - D I S C L O S U R E -dAPPTYPESH="<filename>". <filename> is the name of the file with user defined structures and data declarations. In the example below two variables and one data type are defined by the user which are referenced in files generated by SG. Variables are defined in the user's file "user.c" and referenced in the produced file "cfg.c". The data type is defined in the user's file "user.h" and referenced in the produced file "cfg.c". The user's code can be the following: USER.H file: typedef struct tagMSG MSGTYPE; struct tagMSG { TickType timeStamp; int x; }; extern MSGTYPE MsgA; User's Manual 176 OSEK Operating System -- Rev 1.2 Building of Application MOTOROLA #define R E Q U I R E D Building of Application Action Sequence to Build an Application MYISRSTACKSIZE100 extern char MyIsrStack[MYISRSTACKSIZE]; USER.C file: A G R E E M E N T #include "user.h" /* include user defined data type */ ... char MyIsrStack[MYISRSTACKSIZE]; ... int varA = 22; /* user defined variables */ int varB = 0; ... CFG.C file (generated by SG): ... #if defined(APPTYPESH) #include APPTYPESH /* user's header file */ #endif /* defined(APPTYPESH) */ ... /* SG generated code referring to user's type and data */ ... The compiler command line has the following option: -dAPPTYPESH="USER.H". The code of user's tasks and functions should be developed according to common rules of the C language. But some exceptions exist: * The keyword TASK and ISR should be used to define a task and ISR correspondingly; * For objects controlled by the OSEK Operating System the data types defined by the system must be used. The data types are described at the end of previous sections and in Section 17 System Services. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Building of Application 177 N O N - D I S C L O S U R E Other variants are also possible. R E Q U I R E D Building of Application 14.3.3 Compiling and Linking When all needed header and source files are created or produced by the System Generator an application can be compiled and linked (for details see Appendix 15 HC12 Platform-Specific Features). Linking process is controlled by the typical linker directive file. A G R E E M E N T 14.4 Sample Application N O N - D I S C L O S U R E In Appendix A Sample Application the code of an OSEK OS based application is provided. This code is a simple demonstration of Operating System mechanisms. It also demonstrates how to write the configuration file and source code. User's Manual 178 OSEK Operating System -- Rev 1.2 Building of Application MOTOROLA 15.2 Compiler-Specific Features . . . . . . . . . . . . . . . . . . . . . . . . . .179 15.3 Interrupt Flag Manipulation Specific Features . . . . . . . . . . . .180 15.4 HC12 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .182 15.5 Task Stack Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .192 15.2 Compiler-Specific Features To use OSEK OS after installation the Cosmic C-compiler for MC68HC12 should be installed on the computer. It is necessary to call the DOS prompt under Windows NT to run the NMAKE utility. 15.2.1 OSEK OS Environment Variables It is recommended to add environment variables and paths to access compiler directories and OSEK directory. Installation procedure suggests the user to set these variables automatically and place it into OSEK OS Environment Configuration file (MAKE.BAT by default). If they were not set during installation the user should do it manually.These variables are the following: OSEKDIR = [...]\OSEK - path to the OSEK directory For the Cosmic compiler: CXPATH = [...]\H6812 - path to the Cosmic header files directory CXLIB = [...]\LIB - path to the Cosmic library files directory OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual HC12 Platform-Specific Features 179 R E Q U I R E D 15.1 Contents A G R E E M E N T Section 15. HC12 Platform-Specific Features N O N - D I S C L O S U R E User's Manual -- OSEK Operating System See the file "makefile" in the OSEK\SAMPLE directory for additional information. 15.2.2 Cosmic Software In case of optimization-related errors in the compiler's code generation It is recommended to switch off optimizer by use "-no" option for compiler. (The "-no" option is used in the sample makefile for debug version of the executable code). N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D HC12 Platform-Specific Features Definitions for Cosmic C-compiler The user should set the next compiler definitions to provide the selection of the Cosmic platform and the selection of the board being used: * OSCOSMIC12 for the selection of the Cosmic platform. * OSHC12A4 for selection of the board HC812A4EVB. * OSHC12B32 for selection of the board M68HC12B32EVB. * OSHC12D60 for selection of the board M68EVB912D60. * OSHC12D128 for selection of the board M68EVB912D60 with DA128 chip. 15.3 Interrupt Flag Manipulation Specific Features CPU12 exceptions include resets, an unimplemented opcode trap, a software interrupt instruction, X-bit interrupts and I-bit interrupts. Exceptions can be classified by the effect of the X and I interrupt mask bits in Condition Code Register (CCR) on recognition of a pending request. Resets, the unimplemented opcode trap, and the SWI instruction are not affected by the X and I mask bits. COP resets have register values to enable/disable. Interrupt service requests from the XIRQ pin are inhibited when X = 1, but are not affected by the I bit. All other interrupts are inhibited when I = 1. This version of the OSEK Operating System manipulates with CCR X-bit and I-bit only (external interrupt registers are not affected), therefore it is not possible to use OSEK services from interrupts below XIRQ. User's Manual 180 OSEK Operating System -- Rev 1.2 HC12 Platform-Specific Features MOTOROLA For OS/12 the following logicmask values are valid: 0x10 - I-bit interrupts are enabled (CCR I-bit is cleared, X-bit is set); 0x40 - X-bit interrupts are enabled (CCR X-bit is cleared, I-bit is set); 0x50 - I-bit and X-bit interrupts are enabled (CCR I-bit and X-bit are cleared); 0x00 - internal interrupts are disabled (CCR I-bit and X-bit are set). Physical interrupt mask (value of CCR I-bit and X-bit) is ( ~logicmask )&0x50. All other bits of CCR are not affected in OSEK system services. Notice, that system services (EnableInterrupt, DisableInterrupt, GetInterruptMask) proceeds their parameter as full mask (8-bit) to be applied to CCR but affected on X-bit and I-bit only. GetInterruptMask returns mask that can be safely provided to other system services. DisableInterrupt inverts mask argument before set it. E.g. call DisableInterrupt( 0x00) sets interrupt mask 0x10 (logicmask). NOTE: It is possible to use EnterISR()/ExitISR() services from internal interrupts only (as mentioned above). OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual HC12 Platform-Specific Features 181 A G R E E M E N T In OSEK OS v.2.0 it is necessary to use logical interrupt descriptors(logicmask). N O N - D I S C L O S U R E HC12 OS services for interrupt flag manipulation simply disable and enable interrupts and inquire the current status of the interrupt flags (CCR X-bit and I-bit). If a task is preempted by other task or suspended its interrupt mask is saved. When the task is resumed its saved interrupt mask is restored. When a task is activated it has either the interrupt mask specified in the task definition statement (attribute InterruptMask in OIL-file) or the interrupt mask specified in the interrupt definition statement (attribute TaskLevelMask in OIL-file - common mask value for all tasks which have undefined InterruptMask attribute) R E Q U I R E D HC12 Platform-Specific Features Interrupt Flag Manipulation Specific Features 15.4 HC12 Features 15.4.1 Base Page Memory Usage In general, the system configuration option HCBasePage is of considerable importance for the OSEK Operating System for HC12 MCU. The average size of the OSEK OS kernel version with HCBasePage turned on is significantly smaller than the size of the version with extended addressing (HCBasePage is turned off). Exact characteristics are provided in Appendix C Memory Requirements. This feature can be important for applications with exacting requirements for memory and performance. Also the task control blocks can be placed into the base page memory, if the system configuration option TaskBasePage is turned on. In this case the user is responsible for the needed amount of RAM in the base page for the desired number of task control blocks (the Cosmic linker option to control the segment size "-m##" can be used for this purpose). This system property increases the overall system performance. N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D HC12 Platform-Specific Features However, it should be kept in mind that not all MCUs based on CPU12 core have base page available for data. For example, MC68HC812A4 uses base page for registers, and using of base page for OSEK OS should be avoided (i.e. both options described above must be turned off) NOTE: The current OSEK Operating System for HC12 has this feature implemented for Cosmic software only. 15.4.1.1 Mapping RAM and REGISTERS In MCUs based on CPU12, RAM and REGISTERS areas may be mapped to any 2K space. This feature is especially important for MCUs like HC12D60, where RAM and register areas by default start from address 0, and 512 bytes of RAM are lost therefore. The following compilation-time variables are used for start addresses: * _BASE defines the start address of the REGISTERS area, * _BASERAM defines the start address of the RAM area. User's Manual 182 OSEK Operating System -- Rev 1.2 HC12 Platform-Specific Features MOTOROLA * basereg defines the start address of the REGISTERS area (i.e. value of _BASE variable), * baseram defines the start address of the RAM area (i.e. value _BASERAM variable). If basereg or baseram are set in makefile, the compiler options and linker directives are adjusted, and initialization of INITRM and INITRG registers is made automatically (corresponding procedure is defined in "vector.c" file). 15.4.2 Interrupt Vector Table The interrupt vector table is defined in the file "vector.c" which is delivered with the OSEK Operating System and located in the [...]\OSEK\SAMPLE directory. This file is the example of the interrupt vector table coding. The user should copy this file into the project directory and there modify it as needed. If D-Bug12 monitor is used for development (like for MC68HC812A4EVB), the vector table is arranged according to the logical vector numbers used by the D-Bug12 v1.0.2 monitor. The real setting of the vectors is performed in main() function via D-Bug12 SetVector function. The sample contains the code needed to set vectors properly for the MC68HC812A4EVB. If the application will be started without D-Bug12, it may be necessary to re-arrange the vector table according to the physical order of the interrupts vectors in the vector table. For example, if SDI is used for development (like for M68EVB912D60), the vector table is arranged according to physical location of the vector numbers. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual HC12 Platform-Specific Features 183 A G R E E M E N T These technique is demonstrated in the sample for Cosmic software. Two variables are defined in makefile: N O N - D I S C L O S U R E Any of these variables or both should be set in compiler options, and memory allocation should be adjusted in linker directives. As very first step of reset handling the INITRM register should be set equal to bits 15:11 of the _BASERAM value, and INITRG register should be set equal to bits 15:11 of the _BASE value. R E Q U I R E D HC12 Platform-Specific Features HC12 Features 15.4.3 The Banked Memory Model Support 15.4.3.1 Banked Memory Model Overview In general, the system configuration option HCBankCode specifies that memory bank switching is supported by the OSEK OS. This property is hardware-dependent and compiler-dependent. The hardwaredependent means that it can be applied only to some micro controllers of the M68HC12 family (MC68HC912DA128/DG128/DT128) which have the ability to extend the address range of the CPU beyond the 64KB limit given by the 16 CPU address lines. The compiler-dependent means that the mechanism of the near and far functions must be supported by compiler. A G R E E M E N T R E Q U I R E D HC12 Platform-Specific Features In case of HCBankCode is set to TRUE the user's application part of code (the task code) will be placed into expanded memory (into the memory banks) and OSEK OS will provide task bank value saving/restoring while OSEK OS manipulates with TASKs allocated to the different banks. OSEK OS code and data will be allocated to nonbanked memory together with interrupt handlers. N O N - D I S C L O S U R E In current version of OSEK OS these properties are implemented for Cosmic C-compilers and the board M68EVB912D60 with DA128 chip (the user should set OSHC12D128 compiler definition). The following diagram illustrates the memory paging scheme: User's Manual 184 OSEK Operating System -- Rev 1.2 HC12 Platform-Specific Features MOTOROLA R E Q U I R E D HC12 Platform-Specific Features HC12 Features Address (hex) Non-banked memory - start-up code - OSEK OS code - ISR $FFFF $08000 A G R E E M E N T Bank 0 $0BFFF $18000 Bank 1 $1BFFF - task code - any functions called from the task/ISR - other application code *** $68000 Bank 6 $6BFFF Figure 15-1. Banked Memory Model 15.4.3.2 Configuration of the Application for Banked Memory In general, the following steps should be performed to configure application for banked memory: 1. Identify application code to be allocated in various banks. Typically, task code as well as application library code may be located in the banked memory; 2. Emphasize the banked code in the source files. Compiler #pragma directive is used to start banked section, which is identified by the section name. Alternative way is to do not explicitly identify banks in the code, and allow linker to do relocation of the code into the banks; 3. Turn on the HCBankCode property in the configuration file. (Note that MemoryBank property of the tasks is ignored, and may have any value therefore. It is designed for future extensions); OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual HC12 Platform-Specific Features 185 N O N - D I S C L O S U R E $0000 R E Q U I R E D HC12 Platform-Specific Features 4. Alter compiler options to make all the functions banked by default. The non-banked functions should have near modifier; 5. In the linker directive file locate banked sections into the physical banks. More details may be found in the sample code and makefile, as well in the compiler User's manuals. A G R E E M E N T The compiler supports bank switching for code only, using the internal window mechanism provided by the MC68HC12 processor, or using any external user provided mechanism. Bank switching is supported via: N O N - D I S C L O S U R E 15.4.3.3 Cosmic Compiler Issue Compiler pragma for banked memory @far type qualifier to describe a function relocated in a different bank. Calling such a function implies a special calling sequence, and a special return sequence. Such a function has to be defined @far and referenced as @far in all the files using it. The compiler also provides a specific option +modf to automatically consider all the functions to be @far. Linker options are required to ensure proper physical and logical addresses computations. The linker is also able to automatically fill banks without any need to take care of the page boundaries. The following #pragma directive is used to start banked section bank1: #pragma section (bank1) Compiler options for banked memory The following compiler option is used to make all functions banked by default (except implicitly defined as near): -m modf:hmodf.h +modf Linker directives for banked memory The following directive is used to locate the banked section bank1 in the physical bank #1: User's Manual 186 OSEK Operating System -- Rev 1.2 HC12 Platform-Specific Features MOTOROLA 15.4.4.1 UseMainStack property It is recommended to turn ON this property. It reduces the needed amount of RAM for stacks, since the same memory area is used during start-up (for main() program), for the interrupt stack and for the scheduler stack. Moreover, the size of the OS code is also reduced (ROM for the Operating System). However, the user is responsible for allocation appropriate stack in the linker directive file. (This file is used as an inline text in the sample makefile). 15.4.4.2 UseSameContext Property It is recommended to turn ON this property to use only preemptive context for all tasks. It is important for CPU12 so the code to process the non-preemptive context is quite big, and it leads to additional ROM and RAM consuming and reduces system performance. When this property is ON, task switching is performed faster and the required ROM amount is reduced. Use of different contexts (preemptive and non-preemptive) have a sense for CPUs with many registers if some of them are not included into the non-preemptive context. 15.4.4.3 InterruptMaskControl Property It is better to keep this property turned OFF, if it is not absolutely necessary to control "I" bit of the Condition Code Register. Using of this property increases the amount of ROM for the OS code and requires additional time for all system services. Generally, this property is intended for CPUs with several interrupt priority levels, e.g. CPU16. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual HC12 Platform-Specific Features 187 A G R E E M E N T 15.4.4 Recommendations on System Properties N O N - D I S C L O S U R E +seg .bank1 -b 0x18000 -p1 R E Q U I R E D HC12 Platform-Specific Features HC12 Features 15.4.4.4 CounterSize Property In spite that CPU12 processes 16-bits variables, the best performance is achieved when operands are byte-sized. Therefore, it is recommended to use 8-bit counters (CounterSize = 8) to increase overall performance and reduce the needed amount of RAM. Of course, it is possible to use 16-bit and 32-bit counters, but it leads to additional RAM and time consuming, especially in case of 32-bit counters! 15.4.4.5 Unused Services To reduce ROM consuming it is recommended to exclude OS services which are not used in the application from the OS code with the help of "excluding" system properties. It helps to save memory. 15.4.5 System Timer Hardware The special OS attributes are introduced to define hardware interrupt source and desired parameters for counter considered to be system timer. In the table below all possible values to define these parameters are listed. N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D HC12 Platform-Specific Features User's Manual 188 OSEK Operating System -- Rev 1.2 HC12 Platform-Specific Features MOTOROLA Table 15-1. Parameters to define System Timer hardware PrescalerValue bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0 TimerModuloValue TIMTOI BCSC BCSB BCSA MCSB MCSA PR2 PR1 PR0 N/A TIMOC0 BCSC BCSB BCSA MCSB MCSA PR2 PR1 PR0 0...65535 TIMOC1 BCSC BCSB BCSA MCSB MCSA PR2 PR1 PR0 0...65535 TIMOC2 BCSC BCSB BCSA MCSB MCSA PR2 PR1 PR0 0...65535 TIMOC3 BCSC BCSB BCSA MCSB MCSA PR2 PR1 PR0 0...65535 TIMOC4 BCSC BCSB BCSA MCSB MCSA PR2 PR1 PR0 0...65535 TIMOC5 BCSC BCSB BCSA MCSB MCSA PR2 PR1 PR0 0...65535 TIMOC6 BCSC BCSB BCSA MCSB MCSA PR2 PR1 PR0 0...65535 TIMOC7 BCSC BCSB BCSA MCSB MCSA PR2 PR1 PR0 0...65535 RTI BCSC BCSB BCSA MCSB MCSA RTR2 RTR1 RTR0 N/A A G R E E M E N T MC68HC812A4 MC68HC912B32, MC68HC912D60, MC68HC912DA128 TIMTOI N/A N/A N/A N/A N/A PR2 PR1 PR0 N/A TIMOC0 N/A N/A N/A N/A N/A PR2 PR1 PR0 0...65535 TIMOC1 N/A N/A N/A N/A N/A PR2 PR1 PR0 0...65535 TIMOC2 N/A N/A N/A N/A N/A PR2 PR1 PR0 0...65535 TIMOC3 N/A N/A N/A N/A N/A PR2 PR1 PR0 0...65535 TIMOC4 N/A N/A N/A N/A N/A PR2 PR1 PR0 0...65535 TIMOC5 N/A N/A N/A N/A N/A PR2 PR1 PR0 0...65535 TIMOC6 N/A N/A N/A N/A N/A PR2 PR1 PR0 0...65535 TIMOC7 N/A N/A N/A N/A N/A PR2 PR1 PR0 0...65535 RTI N/A N/A N/A N/A N/A RTR2 RTR1 RTR0 N/A additionally for MC68HC912D60, MC68HC912DA128 MDC N/A N/A N/A N/A N/A N/A MCPR1 MCPR0 0...65535 The bits 7:6:5 of the prescaler contain the values to be set in the base clock select bits BCSC:BCSB:BCSA of the clock control register CLKCTL. The bits 4:3 of the prescaler contain the values to be set in the module clock select bits MCSB:MCSA of the clock control register CLKCTL. The bits 2:1:0 of the prescaler contain the values to be set either in the timer prescaler select bits PR2:PR1:PR0 of the timer interrupt mask 2 register TMSK2 or in the base clock select bits OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual HC12 Platform-Specific Features 189 N O N - D I S C L O S U R E TimerHardware R E Q U I R E D HC12 Platform-Specific Features HC12 Features R E Q U I R E D HC12 Platform-Specific Features RTR2:RTR1:RTR0 of the real-time interrupt control register RTICTL. The bits 1:0 of prescaler can also contain the values to be set in the Modulus Counter Prescaler select bits MCPR1:MCPR0 of the MCCTL register. NOTE: MC68HC912B32 MCU does not allow the following values of prescaler bits PR2:PR1:PR0: 1:1:0 and 1:1:1. A G R E E M E N T Thus, the system definition statements for the OSEK Operating System for HC12 MCU family has the following form: OS <name> { ... SysTimer = <SysTimerDefined>; TimerHardware = <HardwareType>; Prescaler = <PrescalerDefined>; PrescalerValue = <HardwarePrescaler>; TimerModulo = <ModuloDefined>; TimerModuloValue = <HardwareModulo>; ... }; N O N - D I S C L O S U R E For example, the system timer is based on the Output Compare channel 5 interrupt, with no Prescaler and Modulo Counter value equals 1024. In this case the definition statement can be the following: OS <name> { ... SysTimer = TRUE; TimerHardware = TIMTOI; Prescaler = FALSE; ... }; Another example, the system timer based on the Real-Time Interrupt, with Prescaler value equals 1 and no Modulo value. In this case the definition statement can be the following: OS <name> { ... SysTimer = TRUE; TimerHardware = RTI; Prescaler = TRUE; PrescalerValue = 0x01; User's Manual 190 OSEK Operating System -- Rev 1.2 HC12 Platform-Specific Features MOTOROLA NOTE: The system timer will not be triggered if the EntryExitISR property is turned OFF! 15.4.6 Scheduler Architecture If an application does not use resources, it is strongly recommended to use simplified scheduler (the property SimpleScheduler must be turned ON). In this case all tasks running concurrently must have different priorities.That is, two tasks may have the same priority if they are never both in ready state and they must have different priorities otherwise. The simple scheduler uses prioritized table of task nodes and works faster. It requires less amount of ROM and RAM than the standard scheduler. If an application uses resources or claims to have more than one ready task per priority, the SimpleScheduler option should be turned off. In this case the POSIX-like scheduler is used. To reduce RAM consuming the number of priorities should be kept as small as possible. 15.4.7 Alarms Configuration If the application does not use cyclic alarms, it is recommended to turn CyclicAlarm property OFF. In this case the cyclic field is excluded from the alarm control block, which decreases RAM usage. In addition, the code to handle cyclic alarms is also excluded from the system, decreasing ROM usage and improving performance of the alarm services. As a side effect, stack usage is also decreased, because there is no need to pass cycle parameter for SetAbsAlarm and SetRelAlarm services, and less stack space is required for internal computations. To decrease RAM usage, the AlarmList property may be turned OFF. In this case, the alarms are collected together in one table, and linked to the counter. Therefore, the fields, which are required for list handling, are eliminated from the alarm control block. However, to keep performance the number of alarms attached to one counter, should be minimized. To OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual HC12 Platform-Specific Features 191 N O N - D I S C L O S U R E TimerModulo = FALSE; ... }; A G R E E M E N T R E Q U I R E D HC12 Platform-Specific Features HC12 Features reach that, additional counters may be added, and alarms may be rearranged. If the RAM size is limited, it is highly recommended to turn MinAlarmRAM property ON. In this case alarm control block size is significantly decreased, especially when AlarmList property may be turned OFF. However, the performance is slightly decreased, because some static data are not mirrored in RAM. It should be also kept in mind, that in this case alarms are referenced differently than in case when MinAlarmRAM property is turned OFF. 15.5 Task Stack Size Generally, the recommended minimal task stack size equals: * 24 bytes for extended tasks if no task activation, messages, and there are no interrupts in the system; * 32 bytes for extended tasks if no task activation, messages and interrupts are supported in the system; * 48 bytes for other cases. In order to reduce amount of memory, needed for task stacks, UseCommonArea property may be turned ON. In this case the global data area is used for parameters and local variables for most internal system functions. (For operating system calls convenient compiler generated calls are used). N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D HC12 Platform-Specific Features In particular, UseCommonArea property allows to save stack space while calling the following services: * ActivateTask - up to 4 bytes; * CounterTrigger - up to 12 bytes; * SetRelAlarm/SetAbsAlarm - up to 4 bytes. User's Manual 192 OSEK Operating System -- Rev 1.2 HC12 Platform-Specific Features MOTOROLA 16.2 System Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .193 16.3 Using OS Extended Status for Debugging . . . . . . . . . . . . . . .193 16.4 Context Switch Routines. . . . . . . . . . . . . . . . . . . . . . . . . . . . .194 16.5 Stack Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .195 16.6 Known Problems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .195 In this section some advice is given which may be useful for developers working with the OSEK Operating System. 16.2 System Generation The System Generator is used to generate the code for the OSEK Operating System kernel and all application objects (tasks, messages, etc.). This tool processed the configuration file created by the user and reports about inconsistencies and errors in it. Most of possible mistakes in application configuration process can be eliminated with the help of SG. See Section 12 System Configuration and Section 14 Building of Application about system generation process. If an undocumented problem arises please provide us with the detailed description of it and we will help to resolve the problem. See Section 2.6 Technical Support Information for contact information. 16.3 Using OS Extended Status for Debugging It is strongly recommended to use Operating System Extended Status when you develop an application to analyze return codes of system OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Application Troubleshooting 193 R E Q U I R E D 16.1 Contents A G R E E M E N T Section 16. Application Troubleshooting N O N - D I S C L O S U R E User's Manual -- OSEK Operating System services. Such method is more memory and time consuming but it allows the user to save time for errors eliminating. Error codes returned by the OSEK OS services covers most of possible errors that can arise during development. Therefore it is useful to check these codes after a service call to avoid error that can lead to the system crash. For example, a task can perform the TerminateTask service while it is still occupying a resource. This service will not be performed and the task will remain active (running). In case of Extended Status the E_OS_RESOURCE error code is returned and it is possible to detect this situation. But in the system without Extended Status there is no additional check and this error is not indicated and the application behavior will be unpredictable! When all errors in an application will be eliminated you may turn off the Extended Status and remove additional status checks from the application to get the reliable application of the smaller size. 16.4 Context Switch Routines Breakpoints, traces and time stamps can be integrated individually into the application software with the help of context switch hook routines PreTaskHook and PostTaskHook. N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Application Troubleshooting Example: The user can set time stamps enabling him to trace the program execution at the following locations before calling operating system services: * When activating or terminating tasks; * When setting or clearing events in the case of Extended Tasks; * At explicit points of the schedule (ChainTask, Schedule); * At the beginning or the end of ISR; * When occupying and releasing resources or at critical locations. The Operating System needs not include a time monitoring feature which ensures that each or only, e.g. the lowest-priority task has been activated in any case after a defined maximum time period. User's Manual 194 OSEK Operating System -- Rev 1.2 Application Troubleshooting MOTOROLA Stack errors may be due to the stack pointer being incorrect or to stack contents being incorrect. Stack content problems are possible when using pointers into stack variables, but stack pointer problems seem to be more common. The symptom of either problem is usually a task or ISR executing normally, but then when a return is performed, the program executes at some incorrect address. Problems with a program running wild may sometimes be caught by always filling the unused program memory with $00, which the HC12 `test' opcode does, and setting a breakpoint at the illegal opcode vector address. ISRs using OS services or reenabling interrupts should begin with the EnterISR service and end via the LeaveISR service (see Section 6 Interrupt Processing). If the number of EnterISR and LeaveISR invocations do not match (e.g., in case of nested interrupts), the stack will be incorrect. See also Section 6 Interrupt Processing about using variables in ISRs. Tasks should have enough stack for their execution, therefore it is recommended to pay attention on task definition statements to provide each task with a needed amount of stack. See Section 15 HC12 Platform-Specific Features. 16.6 Known Problems None. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Application Troubleshooting 195 A G R E E M E N T 16.5 Stack Errors N O N - D I S C L O S U R E The user can optionally use hook routines or establish a watchdog task that takes "one-shot displays" of the operating system status. R E Q U I R E D Application Troubleshooting Stack Errors N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Application Troubleshooting User's Manual 196 OSEK Operating System -- Rev 1.2 Application Troubleshooting MOTOROLA 17.1 Contents 17.2 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .197 17.3 Task Management Services . . . . . . . . . . . . . . . . . . . . . . . . . .199 17.4 ISR Management Services . . . . . . . . . . . . . . . . . . . . . . . . . . .210 17.5 Resource Management Services . . . . . . . . . . . . . . . . . . . . . .220 17.6 Counters and Alarms Management Services . . . . . . . . . . . . .225 17.7 Event Management Services . . . . . . . . . . . . . . . . . . . . . . . . .242 17.8 Communication Management Services . . . . . . . . . . . . . . . . .249 17.9 Operating System Execution Control . . . . . . . . . . . . . . . . . . .259 R E Q U I R E D Section 17. System Services A G R E E M E N T User's Manual -- OSEK Operating System This section provides detailed description of all OSEK OS run-time services including hook routines. Also declarations of system objects - the constructional elements - are described here. The services are arranged in logical groups - for the task management, the interrupt management, etc. Examples of code are also provided for every logical group. These examples have no practical meaning, they only show how it is possible to use OS calls in an application. The following scheme is used for service description: Declaration element: Syntax: Operating System interface in ANSI-C syntax. Input List of all input parameters. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Services 197 N O N - D I S C L O S U R E 17.2 General R E Q U I R E D System Services Description: Explanation of the constructional element. Particularities: Explanation of restrictions relating to the utilization. Conformance: Specifies the lowest Conformance Class where the declaration element is provided. N O N - D I S C L O S U R E A G R E E M E N T Service description: Syntax: Operating System interface in ANSI-C syntax. The return value of the service is always of data type StatusType. Input: List of all input parameters. Output: List of all output parameters. Transfers via the memory use the memory reference as input parameter and the memory contents as output parameter. To clarify the description, the reference is already specified among the output parameters. Description: Explanation of the functionality of the operating system service. Particularities: Explanations of restrictions relating to the utilization of the service. Status: List of possible return values. Standard: List of return values provided in the operating system's standard version. Special case - service does not return. Extended: List of additional return values in the operating system's extended version. Conformance: Specifies the lowest Conformance Class where the service is provided. The specification of operating system services uses the following naming conventions for data types: ...Type: describes the values of individual data. User's Manual 198 OSEK Operating System -- Rev 1.2 System Services MOTOROLA ...RefType: describes the identifier referencing an object1. It is also possible to see all predefined OSEK OS data types in system header files. 17.3 Task Management Services R E Q U I R E D System Services Task Management Services * TaskType The abstract data type for task identification; * TaskRefType The data type to refer variables of the TaskType data type; * TaskStateType The data type for variables to store the state of a task; * TaskStateRefType The data type to refer variables of the TaskStateType data type. 17.3.2 Constants The following constants are used within the OSEK Operating System to indicate task states: * RUNNING Constant of data type TaskStateType for task state running * WAITING Constant of data type TaskStateType for task state waiting * READY Constant of data type TaskStateType for task state ready * SUSPENDED Constant of data type TaskStateType for task state suspended 1. E.g., a pointer or an index OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Services 199 N O N - D I S C L O S U R E The OSEK OS establishes the following data types for the task management: A G R E E M E N T 17.3.1 Data types The following constant is used within the OSEK OS to indicate task: * INVALID_TASK Constant of data type TaskType for a not defined task 17.3.3 Conventions Within the application of the OSEK OS a task should be defined according to the following pattern: TASK ( TaskName ) { ... } The name of the task function will be generated from TaskName by macro TASK. The only data types must be used for operations with tasks. 17.3.4 Task Declaration To refer to a task the constructional element should be used to declare the task before references to it: N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D System Services Syntax: DeclareTask( TaskType <TaskName> ) Input: * <TaskName> - a reference to the task Description: DeclareTask serves as an external declaration of a task. The function and use of this service are similar to that of the external declaration of variables. Particularities: none Conformance: BCC1, BCC2, ECC1, ECC2 User's Manual 200 OSEK Operating System -- Rev 1.2 System Services MOTOROLA Syntax: StatusType ActivateTask( TaskType <TaskName> ); Input: * <TaskName> - a reference to the task. Output: * None. Description: The specified task TaskName is transferred from the suspended state into the ready state. All needed actions for task initialization are accomplished by the system according to information from the task configuration table (e.g., dynamic stack and node allocation). Particularities: The service may be called both on the task level (from a task) and the interrupt level (from ISR). This service may be called also by StartupHook hook routine. In the case "call from ISR", the operating system will reschedule tasks only after the ISR completion. If the system configuration option ActivateTask is turned off the service is excluded from the OSEK OS code. Status: * * Standard: - E_OK - no error; Extended: - E_OS_ID - E_OS_LIMIT OSEK Operating System -- Rev 1.2 MOTOROLA - the task identifier TaskName is invalid; - too many task activations of the specified task or there is no enough resources to activate the task. User's Manual System Services 201 N O N - D I S C L O S U R E 17.3.5 ActivateTask A G R E E M E N T R E Q U I R E D System Services Task Management Services Conformance: BCC1, BCC2, ECC1, ECC2 17.3.6 TerminateTask Syntax: StatusType TerminateTask( void ); Input: * A G R E E M E N T R E Q U I R E D System Services None. Output: * None. Description: This service causes the termination of the calling task. The calling task is transferred from the running state into the suspended state and releases all occupied system resources (that is, the stack, the task node, etc.) except task has multiply activation requests. Particularities: N O N - D I S C L O S U R E The resources occupied by the task must have been released before. If the call was successful, TerminateTask does not return to the call level and the status can not be evaluated. If the service TerminateTask is called successfully, it enforces a rescheduling. If the system with extended status is used, the service returns in case of error, and provides a status which can be evaluated in the application. If the system configuration option TerminateTask is turned off the service is excluded from the OSEK OS code. Status: * Standard: - No return to the caller. * Extended: - E_OS_RESOURCE User's Manual 202 - the task still occupies resources; OSEK Operating System -- Rev 1.2 System Services MOTOROLA BCC1, BCC2, ECC1, ECC2 17.3.7 ChainTask Syntax: StatusType ChainTask( TaskType <TaskName> ); Input: * <TaskName> - a reference to the sequential succeeding task to be activated. Output: * None. Description: This service causes the termination of the calling task. After termination of the calling task a succeeding task <TaskName> is activated sequentially. Using this service, it ensures that the succeeding task only starts to run after the calling task has been terminated. Particularities: If the succeeding task is identical with the current task, this does not result in multiple requests. In this case the task will be terminated and after that activated again. It can be used, e.g. if multiple activation is disabled but it is needed to restart a task. If it is not needed to have such tricks the system property ChainTaskItself can be turned off to decrease the task control block size. The resources occupied by the calling task must have been released before. If called successfully, ChainTask does not return to the call level and the status can not be evaluated. In this case a rescheduling is enforced. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Services 203 A G R E E M E N T Conformance: - a call at the interrupt level. N O N - D I S C L O S U R E - E_OS_CALLEVEL R E Q U I R E D System Services Task Management Services R E Q U I R E D System Services If the version with Extended Status is used, the service returns in case of error to the calling task, and provides a status which can be evaluated by the application. If the system configuration option ChainTask is turned off the service is excluded from the OSEK OS code. N O N - D I S C L O S U R E A G R E E M E N T Status: * Standard: - If the service is called successfully, then no return to the caller; * Extended: - E_OS_ID - E_OS_LIMIT - E_OS_RESOURCE - E_OS_CALLEVEL Conformance: - the task identifier is invalid; - too many activations of <TaskName> or there is not enough resources to activate the task. - the calling task still occupies resources; - a call at the interrupt level. BCC1, BCC2, ECC1, ECC2 17.3.8 Schedule Syntax: StatusType Schedule( void ); Input: * None. Output: * None. Description: If a higher-priority task is ready, the current task is put into the ready state and a higher-priority task is executed. Otherwise the calling task is User's Manual 204 OSEK Operating System -- Rev 1.2 System Services MOTOROLA continued without delay. By means of using this service the task explicitly yields control to a higher-priority ready task (if any exists). Particularities: In not full-preemptive systems Schedule enables a processor assignment to other tasks in application-specific locations. Schedule does not cause rescheduling if task owns RES_SCHEDULER as resource (See Section 17.5.4 GetResource). If the system configuration option Schedule is turned off the service is excluded from the OSEK OS code. Status: * * Standard: - E_OK - no error. Extended: - E_OS_CALLEVEL - a call at the interrupt level. Conformance: BCC1, BCC2, ECC1, ECC2 A G R E E M E N T R E Q U I R E D System Services Task Management Services Syntax: StatusType GetTaskId( TaskRefType <TaskName> ); Input: * None. Output: * <TaskName> - a reference to the task which is currently active. The system saves the task reference into the variable <TaskName>. Description: This system service returns the name (<TaskName>) of the task which is currently active. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Services 205 N O N - D I S C L O S U R E 17.3.9 GetTaskId R E Q U I R E D System Services Particularities: This service is useful, for instance, in the case if two or more tasks shares the same piece of code and in some point of the code the coming actions depend on which task is executed in the moment. This service may be called by ErrorHook, PreTaskHook and PostTaskHook hook routines. If the name of the task can not be evaluated (no task currently active), the value INVALID_TASK will be returned. A G R E E M E N T If the system configuration option GetTaskId is turned off the service is excluded from the OSEK OS code. Status: * * Standard: - E_OK - no error. Extended: - E_OS_CALLEVEL - a call at the interrupt level. Conformance: BCC1, BCC2, ECC1, ECC2 N O N - D I S C L O S U R E 17.3.10 GetTaskState Syntax: StatusType GetTaskState( TaskType <TaskName>, TaskStateRefType <State> ); Input: * <TaskName> - a reference to the task. Output: * <State> - a reference to the state of task <TaskName>. Description: Returns the state of the specified task <TaskName> (running, ready, waiting, suspended) at the time of calling GetTaskState. User's Manual 206 OSEK Operating System -- Rev 1.2 System Services MOTOROLA Within a full-preemptive system, calling this operating system service only provides a meaningful result if the task runs in an interrupt disabling state at the time of calling. When a call is made from a task in a fullpreemptive system, the result may already be incorrect at the time of evaluation. If the system configuration option GetTaskState is turned off the service is excluded from the OSEK OS code. Status: * * Standard: - E_OK - no error. Extended: - E_OS_ID - the task identifier is invalid. Conformance: BCC1, BCC2, ECC1, ECC2 17.3.11 GetTCBInfo Syntax: StatusType GetTCBInfo( TaskControlBlockRefType <TaskControlBlock>); Input: * None. Output: * <TaskControlBlock> - a reference to a memory block where contents of the running task control block are to be copied. Description: OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Services 207 A G R E E M E N T The service may be called both on the task level (from a task) and the interrupt level (from ISR). This service may be called by ErrorHook, PreTaskHook and PostTaskHook hook routines. N O N - D I S C L O S U R E Particularities: R E Q U I R E D System Services Task Management Services R E Q U I R E D System Services Copies contents of the running task control block by the address specified in <TaskControlBlock> parameter. This service is not defined in the OSEK OS v.2.0 rev. 1 specification. This is an extension of OSEK OS. Particularities: N O N - D I S C L O S U R E A G R E E M E N T The service may be called both on the task level (from a task) and the interrupt level (from ISR). This service may be called by ErrorHook, PreTaskHook and PostTaskHook hook routines. If called by PreTaskHook hook routine this service copies contents of a control block of a task transiting to the running state, that is task being started or resumed. If called by PostTaskHook hook routine this service copies contents of a control block of a task transiting to the waiting, ready or suspended state, that is task being terminated or preempted. There is no memory control performed. User is responsible to ensure that <TaskControlBlock> parameter points to appropriate memory block. The system configuration option GetTCBInfo must be turned on to include this service in the OSEK OS code. Status: * * Standard: - E_OK - no error. Extended: - E_OS_NOFUNC - no running task, nothing done. Conformance: BCC1, BCC2, ECC1, ECC2 17.3.12 Examples for Task Management Services The example below assumes three tasks TaskA, TaskB and TaskC. These tasks use all OSEK OS task management services to coordinate each other. User's Manual 208 OSEK Operating System -- Rev 1.2 System Services MOTOROLA The following definitions can be made in the definition file (for HC08): A G R E E M E N T ... TASK TaskA { TYPE = BASIC; SCHEDULE = FULL; AUTOSTART = TRUE; PRIORITY = 3; StackMethod = OWNSTACK; STACKSIZE = 64; }; TASK TaskB { TYPE = EXTENDED; SCHEDULE = FULL; AUTOSTART = FALSE; PRIORITY = 2; StackMethod = POOLSTACK; StackPool = POOL1; }; TASK TaskC { TYPE = EXTENDED; SCHEDULE = FULL; AUTOSTART = TRUE; PRIORITY = 1; StackMethod = NODESTACK; }; ... R E Q U I R E D System Services Task Management Services N O N - D I S C L O S U R E The C-language file: DeclareTask( TaskA ) DeclareTask( TaskB ) DeclareTask( TaskC ) TASK( TaskA ) { TaskType task; TaskControlBlockType tcb; ... /* any user's code */ ActivateTask( TaskB ); /* activate TaskB */ Schedule(); /* yields CPU to a higher-priority task */ GetTaskId( &task ); /* copies contents of TaskA control */ GetTCBInfo( &tcb ); /* block to tcb variable */ if( task == TaskA ) ActivateTask( TaskC ); else ChainTask( TaskB ); ... /* any user's code */ TerminateTask(); } OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Services 209 R E Q U I R E D System Services TASK( TaskB ) { TaskStateType state; EventMaskType cc = 0x4; ... /* any user's code */ N O N - D I S C L O S U R E A G R E E M E N T GetTaskState( TaskC, &state ); /* check the state of TaskC */ switch( state ) /* and perform appropriate actions */ { case READY: break; case WAITING: SetEvent( TaskC, cc ); break; case SUSPENDED: ChainTask( TaskC ); break; } ... /* any user's code */ } TASK( TaskC ) { TaskStateType stateA, stateB; ... /* any user's code */ while( 1 ) { GetTaskState( TaskA, &stateA ); GetTaskState( TaskB, &stateB ); if( stateA == READY && stateB == SUSPENDED ) ChainTask( TaskB ); if( stateB == READY && stateA == SUSPENDED ) ChainTask( TaskA ); if( stateA == READY && stateB == READY ) Schedule(); ... /* any user's code */ } } 17.4 ISR Management Services 17.4.1 Data Types The OSEK OS establishes the following data types for the interrupt management: * IntDescriptorType - the data type for logical interrupt descriptors; User's Manual 210 OSEK Operating System -- Rev 1.2 System Services MOTOROLA * INITIAL_INTERRUPT_DESCRIPTOR - constant of data type IntDescriptorType for initial interrupt level (see Section 11.5 Start-up Routine). 17.4.2 Constants 17.4.3 Conventions Within the application an Interrupt Service Routine should be defined according to the following pattern: ISR( IsrName ) { ... } The keyword ISR is the macro for compiler specific interrupt function modifier, which is used to generate valid code to enter and exit ISR. If Interrupt Service Routine is defined by means of keyword ISR usage, then it should be declared according to the following pattern: DeclareISR1( IsrName ) The same name shall be used for corresponding ISR object definition (see Section 13.11 ISR Definition). 17.4.4 EnterISR Syntax: StatusType EnterISR( void ); Input: 1. This service is not established by OSEK OS v.2.0 Spec. This is an extension of OSEK OS. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Services 211 A G R E E M E N T IntDescriptorRefType - the data type to refer variables of the IntDescriptorType data type. N O N - D I S C L O S U R E * R E Q U I R E D System Services ISR Management Services R E Q U I R E D System Services * None. Output: * None. Description: A G R E E M E N T EnterISR establishes conditions needed to request OS services within an interrupt service routine. Inside EnterISR the following activities are executed if needed: * Registration of the switching to the interrupt level inside the operating system; * A switch of the current context (to the ISR stack). This function is called from the begin of the interrupt service routine, when hardware registers are pushed onto the current stack either by hardware or by compiler generated code. This way, the context of the running task, or ISR, or scheduler idle loop is known on the function entry. This context is named interrupt stack frame. N O N - D I S C L O S U R E If the task is interrupted, then the pointer to the interrupt stack frame is stored in the stack pointer field of the running task. After that the top of the ISR stack is loaded into the CPU stack pointer, and value of the nested interrupts counter is incremented. If the ISR is interrupted, then the value of the system counter of nested interrupts is advanced by one, and function returns to the caller. If the scheduler idle loop is interrupted, then interrupt stack frame is ignored, because LeaveISR function returns directly to the scheduler idle loop. The top of the ISR stack is loaded into the CPU stack pointer, and value of the system counter of nested interrupts is changed to one. Particularities: EnterISR establishes the possibility to use operating system services in an ISR. It is necessary to place EnterISR before the first call of an operating system service. User's Manual 212 OSEK Operating System -- Rev 1.2 System Services MOTOROLA R E Q U I R E D System Services ISR Management Services See description of interrupt categories in section Section 6.4 ISR Categories. This service is not implemented if the system configuration option EntryExitISR or EnterISR are turned off in the configuration file. * Standard: - None. * Extended: - None. Conformance: A G R E E M E N T Status: BCC1, BCC2, ECC1, ECC2 17.4.5 LeaveISR Syntax: StatusType LeaveISR( void ); Input: None. Output: * None. Description: LeaveISR is the counterpart of EnterISR and resets the conditions to request operating system services in an ISR. Inside LeaveISR the following functions are executed if needed: * Registration of the switching back from the interrupt level inside the operating system; * A switch of the current context (for example a switch from the ISR stack back to the OS context or to the context of the task running before). In case of an error the function returns to the call level. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Services 213 N O N - D I S C L O S U R E * R E Q U I R E D System Services This function is called in the end of the interrupt service routine. If the ISR was interrupted by the corresponding EnterISR, then the value of the system counter of nested interrupts is decremented by one, and the function returns to the caller, because the current ISR is considered as nested one. N O N - D I S C L O S U R E A G R E E M E N T If the caller is the outermost ISR (task or scheduler idle loop was interrupted), then the function calls the scheduler to update the pointer to the running task. After this call the function loads the task stack pointer into the CPU stack pointer in assumption, that task stack pointer contains the address of valid interrupt stack frame. If there is no running task, then functions goes directly to the scheduler idle loop. In any case the value of the nested interrupts counter is decremented by one. Particularities: LeaveISR eliminates the possibility of using OS services in an ISR. It is highly recommended to place LeaveISR at the end of the ISR. See description of interrupt categories in section Section 6.4 ISR Categories. This service is not implemented if the system configuration option EntryExitISR or LeaveISR are turned off in the configuration file. Status: * Standard: - None. * Extended: - None. Conformance: BCC1, BCC2, ECC1, ECC2 17.4.6 EnableInterrupt Syntax: StatusType EnableInterrupt( IntDescriptorType <Mask> ); User's Manual 214 OSEK Operating System -- Rev 1.2 System Services MOTOROLA <Mask> - a mask of interrupts to be enabled. In the mask, a "1" means "enable". Output: * None. Description: This service enables interrupts specified by <Mask>. In the case if several interrupts can be controlled simultaneously, this service allows enabling of several interrupts. Particularities: The service may be called from an ISR and from the task level. For HC12 this service is intended to control only the "I" bit in the Condition Code Register. This service should only be used with care. It destroys the contents of CCR according to C language conventions. In case of use it is highly recommended to know the reaction upon system behavior! To save the current state of interrupts the application must use GetInterruptDescriptor before. This service is executed also in case of return of the state is not equal E_OK. This service is not implemented if the system configuration option EntryExitISR or EnableInterrupt are turned off in the configuration file. Status: * * Standard: - E_OK - no error. Extended: - E_OS_NOFUNC OSEK Operating System -- Rev 1.2 MOTOROLA - at least one of the interrupts was not disabled. User's Manual System Services 215 A G R E E M E N T * N O N - D I S C L O S U R E Input: R E Q U I R E D System Services ISR Management Services Conformance: BCC1, BCC2, ECC1, ECC2 17.4.7 DisableInterrupt Syntax: StatusType DisableInterrupt( IntDescriptorType <Mask> ); Input: * A G R E E M E N T R E Q U I R E D System Services <Mask> - a mask of interrupts to be disabled. In the mask, a "1" means "disable". Output: * None. Description: This service disables interrupts specified by <Mask>. In the case if several interrupts can be controlled simultaneously, this service allows disabling of several interrupts. Particularities: N O N - D I S C L O S U R E The service may be called from an ISR and from the task level. For HC12 this service is intended to control only the "I" bit in the Condition Code Register. This service should only be used with care. It destroys the contents of CCR according to C language conventions. In case of use it is highly recommended to know the reaction upon system behavior! To save the current state of interrupts the application must use GetInterruptDescriptor before. This service is executed also in case of return of the state is not equal E_OK. This service is not implemented if the system configuration option EntryExitISR or DisableInterrupt are turned off in the configuration file. Status: User's Manual 216 OSEK Operating System -- Rev 1.2 System Services MOTOROLA - no error. Extended: - E_OS_NOFUNC Conformance: - at least one of the interrupts was not enabled. BCC1, BCC2, ECC1, ECC2 17.4.8 GetInterruptDescriptor Syntax: StatusType GetInterruptDescriptor( IntDescriptorRefType <Mask> ); Input: * None. Output: * <Mask> - a reference to the interrupt mask to be filled. In the mask, a "1" means (Group of) Interrupt is enabled". Description: Query of interrupt status and returns the current CPU interrupt mask. Particularities: The service may be called from an ISR and from the task level. For HC12 this service is intended to get only the value of the "I" bit in the Condition Code Register. This service is not implemented if the system configuration option EntryExitISR or GetInterruptDescriptor are turned off in the configuration file. Status: * Standard: OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Services 217 A G R E E M E N T * Standard: - E_OK N O N - D I S C L O S U R E * R E Q U I R E D System Services ISR Management Services R E Q U I R E D System Services - E_OK * - no error. Extended: - None. Conformance: BCC1, BCC2, ECC1, ECC2 17.4.9 Examples for Interrupt Management Services A G R E E M E N T Below examples for ISR category 1, 2 and 3 are presented. The following definitions can be made in the definition file (for HC08): N O N - D I S C L O S U R E ... OS myOS { ... IsrStackSize = 64; InterruptMaskControl = TRUE; DisableInterruptMask = 0x0; EnableInterruptMask = 0x8; TaskLevelMask = 0x8; ... }; TASK TaskB { TYPE = EXTENDED; SCHEDULE = FULL; PRIORITY = 2; AUTOSTART = FALSE; StackMethod = POOLSTACK; StackPool = POOL1; }; TASK IndTask { TYPE = BASIC; SCHEDULE = FULL; AUTOSTART = TRUE; PRIORITY = 1; StackMethod = OWNSTACK; STACKSIZE = 64; }; COUNTER Ctr1 { MAXALLOWEDVALUE = 24; TICKSPERBASE = 1; }; MESSAGE Temp { TYPE = UNQUEUEDMESSAGE; ITEMTYPE = "char"; ITEMS = 1; WithCopy = TRUE; User's Manual 218 OSEK Operating System -- Rev 1.2 System Services MOTOROLA R E Q U I R E D System Services ISR Management Services A G R E E M E N T }; MESSAGE Wrn { TYPE = QUEUEDMESSAGE; ITEMTYPE = "MSGCTYPE"; ITEMS = 6; ReceiverNum = 3; }; ISR ISR1_handler { CATEGORY = 1; }; ISR ISR2_handler { CATEGORY = 2; }; ISR ISR3_handler { CATEGORY = 3; }; ... The C-language code can be the following (for HC08): ISR category 1: char CREG, DREG; char data1; DeclareISR( ISR1_handler ) ... N O N - D I S C L O S U R E ISR( ISR1_handler ) { if( CREG != 0xC0 ) CREG |= 0x40; else CREG |= 0x03; DREG = data1; } ISR category 2: TaskStateType stateB; DeclareCounter( Ctr1 ) DeclareTask( TaskB ) DeclareISR( ISR2_handler ) ... ISR( ISR2_handler ) { CounterTrigger( Ctr1 ); GetTaskState( TaskB, &stateB ); if( stateB == SUSPENDED ) ActivateTask( TaskB ); } ISR category 3: DeclareTask( IndTask ) OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Services 219 N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D System Services DeclareISR( ISR3_handler ) OSMSGTemp _Temp; OSMSGWrn _Wrn; int temp; ISR( ISR3_handler ) { /* normal temperature, do nothing */ if( (temp >= LIMIT_L ) && (temp <= LIMIT_H) ) goto exit; /* temperature is below critical value: */ if( LIMIT_L >= temp ) { EnterISR(); SendMessage( Temp, _Temp ); /* send msg to notify */ goto leave; } /* temperature is higher critical value: */ if( (temp >= LIMIT_H) ) { EnterISR(); SendMessage( Wrn, _Wrn ); /* send alarm message */ ActivateTask( IndTask ); leave: LeaveISR(); } exit: ; } 17.5 Resource Management Services 17.5.1 Data types The OSEK OS establishes the following data type for the resource management: * ResourceType - the abstract data type for referencing a resource; The only data type must be used for operations with tasks. 17.5.2 Constants * RES_SCHEDULER - constant of data type ResourceType (see Section 7.3.2 Scheduler as a Resource). User's Manual 220 OSEK Operating System -- Rev 1.2 System Services MOTOROLA R E Q U I R E D System Services Resource Management Services 17.5.3 Resource Declaration To refer to a resource the constructional element should be used to declare the resource before its using: Syntax: DeclareResource( ResourceType <ResName> ) Input: <ResName> Description: DeclareResource serves as an external declaration of a resource. The function and use of this service are similar to that of the external declaration of variables. Particularities: none Conformance: BCC1, BCC2, ECC1, ECC2 17.5.4 GetResource Syntax: StatusType GetResource( ResourceType <ResName> ); Input: * <ResName> - a reference to the resource. Output: * None. Description: This call serves to enter a critical section in the code that is assigned to the referenced resource. A critical section must always be left using ReleaseResource. The E_OS_LIMIT error code is not processed yet. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Services 221 A G R E E M E N T - a reference to the resource. N O N - D I S C L O S U R E * R E Q U I R E D System Services Particularities: This function is fully supported only beginning from the Conformance Class BCC2. In the lower Conformance Classes only the standard resource scheduler can be occupied via the constant RES_SCHEDULER. A G R E E M E N T Corresponding calls to GetResource and ReleaseResource should appear within the same function on the same function level. Generally, critical sections should be short. Nested resource occupation is only allowed if the inner critical sections are executed completely within the surrounding critical section. Regarding Extended Tasks, please note that WaitEvent within a critical section is prohibited. E_OS_ACCESS error code is not returned by GetResource service if more than 8 resources (including RES_SCHEDULER) are defined in the application or FastResource configuration option is turned on or ResourceAccessCheck configuration option is turned off. This service is not implemented if the system configuration option Resources or GetResource are turned off in the configuration file. N O N - D I S C L O S U R E Status: * * Standard: - E_OK - no error. Extended: - E_OS_ID - E_OS_ACCESS - E_OS_CALLEVEL - E_OS_LIMIT Conformance: BCC1, BCC2, ECC1, ECC2 User's Manual 222 - the resource identifier is invalid; - the inadmissible access to resource; - a call at the interrupt level is not allowed; - too many resources are occupied in parallel. OSEK Operating System -- Rev 1.2 System Services MOTOROLA Syntax: StatusType ReleaseResource( ResourceType <ResName> ); Input: * <ResName> - a reference to the resource. Output: * None. Description: This call serves to leave the critical section in the code that is assigned to the referenced resource. An ReleaseResource call is a counterpart of an GetResource service call. The E_OS_ID error code is generated in the following cases: * the resource signature is invalid - this object is not resource; * the resource is occupied by another task, the resource is not released in this case; * the resource is not the last occupied resource (a nesting processing error), the resource is released (unlinked from the list) in this case. Particularities: This function is fully supported only beginning from the Conformance Class BCC2. In the lower Conformance Classes only the standard resource scheduler can be released via the constant RES_SCHEDULER. For information on nesting conditions, see particularities of GetResource. This service is not implemented if the system configuration option Resources or ReleaseResource are turned off in the configuration file. Status: OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Services 223 N O N - D I S C L O S U R E 17.5.5 ReleaseResource A G R E E M E N T R E Q U I R E D System Services Resource Management Services * * Standard: - E_OK - no error. Extended: - E_OS_ID - E_OS_NOFUNC - E_OS_CALLEVEL Conformance: - the resource identifier is invalid; - an attempt to release a resource which is not occupied; - a call at the interrupt level is not allowed. BCC1, BCC2, ECC1, ECC2 17.5.6 Examples of Using Resources The example below presents resource management directives. The following definitions can be made in the definition file (for HC08): ... TASK TASK_A { TYPE = EXTENDED; SCHEDULE = FULL; AUTOSTART = FALSE; PRIORITY = 3; StackMethod = POOLSTACK; StackPool = POOL1; }; TASK TASK_B { TYPE = BASIC; SCHEDULE = FULL; PRIORITY = 2; AUTOSTART = TRUE; RESOURCE = { SCI_res }; StackMethod = OWNSTACK; STACKSIZE = 64; }; TASK SCI_TASK { TYPE = BASIC; SCHEDULE = FULL; PRIORITY = 1; AUTOSTART = TRUE; RESOURCE = { SCI_res }; StackMethod = NODESTACK; }; N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D System Services RESOURCE SCI_res { User's Manual 224 OSEK Operating System -- Rev 1.2 System Services MOTOROLA R E Q U I R E D System Services Counters and Alarms Management Services } }; ... The C-language code can be the following: DeclareTask( SCI_TASK ) DeclareResource( SCI_res ) occupy the SCI resource */ user's code */ A G R E E M E N T TASK( SCI_TASK ) { ... GetResource( SCI_res ); /* ... /* ActivateTask( TASK_B ); GetResource( RES_SCHEDULER ); /* ... ReleaseResource( RES_SCHEDULER ); ReleaseResource( SCI_res ); occupy the scheduler resource */ /* user's code */ /* release the scheduler */ /* release the SCI resource */ TerminateTask(); } 17.6 Counters and Alarms Management Services The following data types are established by OSEK OS to work with counters: * CtrRefType - the data type references a counter * TickType - the data type represent count value in system ticks * TickRefType - the data type references data corresponding to the data type TickType * CtrInfoType - the data type represents a structure for storage of counter characteristics. This structure has the following elements: - maxallowedvalue - maximum possible allowed counter value; OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Services 225 N O N - D I S C L O S U R E 17.6.1 Data Types and Identifiers R E Q U I R E D System Services - ticksperbase - mincycle All elements have the data type TickType, and the structure looks like the following: typedef CtrInfoType tagCIT; struct tagCIT { TickType maxallowedvalue; TickType ticksperbase; TickType mincycle; }; A G R E E M E N T N O N - D I S C L O S U R E - number of ticks required to reach a counter-specific significant unit; - minimum allowed number of ticks for a cyclic alarm (only for system with Extended Status). * CtrInfoRefType - the data type references data corresponding to the data type CtrInfoType The following data type is established by OSEK OS to work with alarms: * AlarmBaseType * AlarmBaseRefType - the data type references data corresponding to the data type AlarmBaseType; * AlarmType - the data type represents a structure for storage of alarm characteristics. It is the same as CtrInfoType; - the data type represents an alarm element. 17.6.2 Constants For system counter, which is always a time counter, the special constants are provided by the operating system: * OSMAXALLOWEDVALUE - maximum possible allowed value of the system timer in ticks (see also Section 13.8.1 Object Attributes); User's Manual 226 OSEK Operating System -- Rev 1.2 System Services MOTOROLA OSTICKSPERBASE - number of ticks that are required to reach 10 OSTICKPERTIMEmilliseconds in the system counter (see also Section 13.8.1 Object Attributes); * OSTICKDURATION - duration of a tick of the system counter in nanoseconds ( defined automatically by System Generator utility (SG) (see Section 12.2 General ), through OSTICKSPERBASE value); * OSMINCYCLE - minimum allowed number of ticks for a cyclic alarm (only for system with Extended Status, see also Section 13.8.1 Object Attributes). 17.6.3 Counter and Alarm Declaration To refer to a counter or alarm the declaration statements should be used to declare the element (counter or alarm) before their using: 17.6.3.1 Counter Declaration N O N - D I S C L O S U R E Syntax: DeclareCounter( CtrRefType <CounterName> ) Input: * <CounterName> - a reference to the counter Description: DeclareCounter serves as an external declaration of a counter. The function and use of this service are similar to that of the external declaration of variables. Particularities: none Conformance: BCC1, BCC2, ECC1, ECC2 OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Services A G R E E M E N T * R E Q U I R E D System Services Counters and Alarms Management Services 227 R E Q U I R E D System Services 17.6.3.2 Alarm Declaration Syntax: DeclareAlarm( AlarmType <AlarmName> ) Input: * <AlarmName> - a reference to the alarm DeclareAlarm serves as an external declaration of an alarm. The function and use of this service are similar to that of the external declaration of variables. Particularities: none Conformance: BCC1, BCC2, ECC1, ECC2 These declarations are equivalent to the external declaration of variables. 17.6.4 InitCounter Syntax: N O N - D I S C L O S U R E A G R E E M E N T Description: StatusType InitCounter( CtrRefType <CounterName>, TickType <Ticks> ); Input: * <CounterName> - a reference to the counter; * <Ticks> - a counter initialization value in ticks. Output: * None. Description: Sets the initial value of the counter with the value <Ticks>. After this call the counter will advance this initial value by one via the following call of User's Manual 228 OSEK Operating System -- Rev 1.2 System Services MOTOROLA CounterTrigger. If there are running attached alarms, then their state stays unchanged. Particularities: This service is not implemented if the system configuration option Counters or InitCounter are turned off in the configuration file. Status: - no error. Extended: - E_OS_ID - E_OS_VALUE - E_OS_CALLEVEL Conformance: A G R E E M E N T * Standard: - E_OK - the counter identifier is invalid; - the counter initialization value exceeds the maximum admissible value; - a call at interrupt level (not allowed). BCC1, BCC2, ECC1, ECC2 17.6.5 CounterTrigger Syntax: StatusType CounterTrigger( CtrRefType <CounterName> ); Input: * <CounterName> - a reference to the counter; Output: * None. Description: Increments the current value of the counter. If the counter reaches the value maxallowedvalue (see Section 17.6.1 Data Types and Identifiers), it is reset to "zero". OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Services 229 N O N - D I S C L O S U R E * R E Q U I R E D System Services Counters and Alarms Management Services R E Q U I R E D System Services If alarms are linked to the counter, the system checks whether they expired after this tick and performs appropriate actions (task activation and event setting). Particularities: Call admissible both from interrupt and task levels. N O N - D I S C L O S U R E A G R E E M E N T Depending on the underlying hardware it is possible that parts of the functionality of CounterTrigger may by done by the hardware. In this case the remaining functionality of CounterTrigger has to be adapted. This service is not implemented if the system configuration option Counters or CounterTrigger are turned off in the configuration file. Status: * * Standard: - E_OK - no error. Extended: - E_OS_ID - the counter identifier is invalid. Conformance: BCC1, BCC2, ECC1, ECC2 17.6.6 AdvanceCounter Syntax: StatusType AdvanceCounter( CtrRefType <CounterName>, TickType <Ticks> ); Input: * <CounterName> - a reference to the counter; * <Ticks > - a number of ticks to be advanced. Output: * None. Description: User's Manual 230 OSEK Operating System -- Rev 1.2 System Services MOTOROLA Advances the current value of the counter. If alarms are linked to the counter, the system checks whether they expired during specified number of ticks and performs appropriate actions (task activation and event setting). This service is not defined in the OSEK OS v.2.0 rev. 1 specification. This is an extension of OSEK OS. Particularities: A G R E E M E N T Call admissible from task level only. This service is not implemented if the system configuration option Counters or AdvanceCounter are turned off in the configuration file. Status: * Standard: - E_OK - E_OS_VALUE - no error; - specified value is greater than maxallowedvalue. Extended: - E_OS_ID - E_OS_CALLEVEL Conformance: - the counter identifier is invalid. - call at interrupt level is invalid. N O N - D I S C L O S U R E * BCC1, BCC2, ECC1, ECC2 17.6.7 GetCounterValue Syntax: StatusType GetCounterValue( CtrRefType <CounterName>, TickRefType <Ticks> ); Input: * <CounterName> - a reference to the counter; Output: * <Ticks> - a counter value in ticks. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Services R E Q U I R E D System Services Counters and Alarms Management Services 231 R E Q U I R E D System Services A reference to the return counter value in ticks. Description: The system service provides the current value of the counter <CounterName> in ticks. Particularities: A G R E E M E N T This service is not implemented if the system configuration option Counters or GetCounterValue are turned off in the configuration file. Status: * * Standard: - E_OK - no error. Extended: - E_OS_ID - E_OS_CALLEVEL - the counter identifier is invalid; - a call at interrupt level (not allowed). Conformance: BCC1, BCC2, ECC1, ECC2 N O N - D I S C L O S U R E 17.6.8 GetCounterInfo Syntax: StatusType GetCounterInfo( CtrRefType <CounterName>, CtrInfoRefType <Info> ); Input: * <CounterName> - a reference to the counter; Output: * <Info> - a reference to the structure with constants of the counter. Description: Returns the counter characteristics into the <Info> structure. For a system counter special constants may be used instead of this service. User's Manual 232 OSEK Operating System -- Rev 1.2 System Services MOTOROLA The return value <Info> is a structure in which the information of data type CtrInfoType is stored. Particularities: The structure consists of two elements in case of the "Standard Status", and of three elements in case of the "Extended Status". This service is not implemented if the system configuration option Counters or GetCounterInfo are turned off in the configuration file. * * Standard: - E_OK A G R E E M E N T Status: - no error. Extended: - E_OS_ID - E_OS_CALLEVEL Conformance: R E Q U I R E D System Services Counters and Alarms Management Services - the counter identifier is invalid; - a call at interrupt level (not allowed). BCC1, BCC2, ECC1, ECC2 Syntax: StatusType SetRelAlarm( AlarmType <AlarmName>, TickType <Increment>, TickType <Cycle> ); Input: * <AlarmName> - a reference to the alarm; * <Increment> - a relative value in ticks; * <Cycle> - an alarm cycle value in ticks in case of cyclic alarm. In case of single alarms, the value cycle has to be equal zero. Output: * None. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Services 233 N O N - D I S C L O S U R E 17.6.9 SetRelAlarm R E Q U I R E D System Services Description: The system service occupies the alarm <AlarmName> element. After this service call the counter will count <Increment> ticks starting from the current counter value at the moment of the call. After <Increment> ticks have elapsed from that moment, the task assigned to the alarm <AlarmName> is activated or the assigned event (only for Extended Tasks) is set. A G R E E M E N T If <Cycle> is unequal 0, the alarm element is logged on again immediately after expiry with the relative value <Cycle>. Otherwise, the alarm triggers only once. Particularities: If the relative value <Increment> is very small, the alarm may immediately expire, and the task may become ready. It is because the certain time is needed for system activities to return to the calling task after the <Increment> ticks for the counter have been set. The alarm <AlarmName> must not already be in use. To change values of alarms already in use the alarm has to be cancelled first. N O N - D I S C L O S U R E This service is not implemented if the system configuration option Alarms or SetRelAlarm are turned off in the configuration file. Status: * * Standard: - E_OK - E_OS_STATE Extended: - E_OS_ID - E_OS_VALUE - no error; - the alarm is already in use. - the alarm identifier is invalid; - the alarm initialization value or cycle value is greater than the maximum allowed value of the counter, or the cycle value is less than the minimum cycle value of the counter. Conformance: User's Manual 234 OSEK Operating System -- Rev 1.2 System Services MOTOROLA BCC1, BCC2; * Events: ECC1, ECC2. 17.6.10 SetAbsAlarm Syntax: StatusType SetAbsAlarm( AlarmType <AlarmName>, TickType <Start>, TickType <Cycle> ); Input: * <AlarmName> - a reference to the alarm; * <Start> -an absolute value in ticks; * <Cycle> - an alarm cycle value in ticks in case of cyclic alarm. In case of single alarms, cycle has to be equal zero. Output: None. A G R E E M E N T * R E Q U I R E D System Services Counters and Alarms Management Services The system service occupies the alarm <AlarmName> element. The counter will count <Start> ticks starting from zero counter value. When <Start> ticks are reached, the task assigned to the alarm <AlarmName> is activated or the assigned event (only for Extended Tasks) is set. If <Cycle> is unequal 0, the alarm element is logged on again immediately after expiry with the relative value <Cycle>. Otherwise, the alarm triggers only once. Particularities: Since the current counter value at the moment of the service call is most likely not equal zero, there exist the some period of time while the counter reaches its maximum allowed value and will be logged on again (its value will become 0). Only starting from zero <Start> ticks will be counted. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Services 235 N O N - D I S C L O S U R E Description: R E Q U I R E D System Services If the absolute value <Start> is very close to the current counter value, the alarm may immediately expire, and the task may become ready. (E.g., the current counter value at the moment of service call equals 253, the maximum allowed counter value equals 255 and the <Start> value is 2.) The alarm <AlarmName> must not already be in use. N O N - D I S C L O S U R E A G R E E M E N T To change values of alarms already in use the alarm has to be cancelled first. This service is not implemented if the system configuration option Alarms or SetAbsAlarm are turned off in the configuration file. Status: * * Standard: - E_OK - E_OS_STATE Extended: - E_OS_ID - E_OS_VALUE - no error; - the alarm is already in use. - the alarm identifier is invalid; - the alarm initialization value or cycle value is greater than the maximum allowed value of the counter, or the cycle value is less than the minimum cycle value of the counter. Conformance: * BCC1, BCC2; * Events: ECC1, ECC2. 17.6.11 CancelAlarm Syntax: StatusType CancelAlarm( AlarmType <AlarmName> ); Input: User's Manual 236 OSEK Operating System -- Rev 1.2 System Services MOTOROLA * <AlarmName> R E Q U I R E D System Services Counters and Alarms Management Services - a reference to the Alarm. Output: None. Description: The service cancels the alarm (transfers it into the stop state). This service is not implemented if the system configuration option Alarms or CancelAlarm are turned off in the configuration file. Status: * * Standard: - E_OK - E_OS_NOFUNC - no error; - the alarm is not in use. Extended: - E_OS_ID - the alarm identifier is invalid. Conformance: BCC1, BCC2, ECC1, ECC2 17.6.12 GetAlarmBase Syntax: StatusType GetAlarmBase( AlarmType <AlarmName>, AlarmBaseRefType <Info> ); Input: * <AlarmName> - a reference to the Alarm; Output: * <Info> - a reference to the structure with constants of the alarm base. Description: OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Services 237 N O N - D I S C L O S U R E A G R E E M E N T Particularities: Returns the alarm base characteristics into the <Info> structure. The return value <Info> is a structure in which the information of data type AlarmBaseType is stored. Particularities: The structure consists of two elements in case of the "Standard Status", and of three elements in case of the "Extended Status". This service is not implemented if the system configuration option Alarms or GetAlarmBase are turned off in the configuration file. Status: * * Standard: - E_OK - no error. Extended: - E_OS_ID - the alarm identifier is invalid. Conformance: BCC1, BCC2, ECC1, ECC2 17.6.13 GetAlarm Syntax: N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D System Services StatusType GetAlarm( AlarmType <AlarmName>, TickRefType <Ticks> ); Input: * <AlarmName> - a reference to the Alarm; Output * <Ticks> - a reference to a variable ( or memory field ) which gets a relative value in ticks before the alarm expires. Description: This service calculates the time in ticks before the alarm expires. If the alarm is not started the E_OS_NOFUNC error code is generated. User's Manual 238 OSEK Operating System -- Rev 1.2 System Services MOTOROLA Particularities: It is up to the application to decide whether for example an alarm may still be useful or not. If <AlarmName> is not in use <Ticks> is 0. This service is not implemented if the system configuration option Alarms or GetAlarm are turned off in the configuration file. R E Q U I R E D System Services Counters and Alarms Management Services * * Standard: - E_OK - E_OS_NOFUNC - no error; - the alarm is not in use. Extended: - E_OS_ID - the alarm identifier is invalid. Conformance: A G R E E M E N T Status: BCC1, BCC2, ECC1, ECC2 17.6.14 Examples for Counter and Alarm Management N O N - D I S C L O S U R E The example shows how counters and alarms can be used. The following definitions are made in the definition file (for HC08): ... TASK TaskTime { TYPE = EXTENDED; SCHEDULE = FULL; AUTOSTART = FALSE; PRIORITY = 3; StackMethod = POOLSTACK; StackPool = POOL1; }; TASK TASK_B { TYPE = BASIC; SCHEDULE = FULL; AUTOSTART = TRUE; PRIORITY = 2; StackMethod = OWNSTACK; STACKSIZE = 64; }; TASK TASK_X { TYPE = BASIC; OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Services 239 R E Q U I R E D System Services A G R E E M E N T SCHEDULE = FULL; AUTOSTART = TRUE; PRIORITY = 1; StackMethod = NODESTACK; }; COUNTER TimeCnt { MAXALLOWEDVALUE = 127; TICKSPERBASE = 1; }; COUNTER DgrCnt { MAXALLOWEDVALUE = 36; TICKSPERBASE = 1; }; ALARM TimeAlm { ACTION = ACTIVATETASK; COUNTER = TimeCnt; TASK = TASK_X; }; ALARM DgrAlm { ACTION = SETEVENT; COUNTER = DgrCnt; TASK = TASK_B; EVENT = DgrAlmEvent; }; EVENT DgrAlmEvent { MASK = 0x01; }; N O N - D I S C L O S U R E MESSAGE Norm { TYPE = QUEUEDMESSAGE; ITEMTYPE = "int"; ITEMS = 6; ReceiverNum = 3; }; ... The alarm TimeAlm activates the task TASK_X when the counter TimeCnt expires. The alarm DgrAlm sets the specified event for the task TASK_B when the counter DgrCnt expires. The C-language code can be the following: DeclareTask( TASK_B ) DeclareTask( TaskTime ) DeclareTask( TASK_X ) DeclareCounter( TimeCnt ) DeclareCounter( DgrCnt ) DeclareAlarm( TimeAlm ) DeclareAlarm( DgrAlm ) OSMSGNorm _Norm; User's Manual 240 OSEK Operating System -- Rev 1.2 System Services MOTOROLA R E Q U I R E D System Services Counters and Alarms Management Services TASK( TaskTime ) { TickType curTime; TickType ticksToExpire; OSBYTE i=0; InitCounter( TimeCnt, 0 ); /* init time counter with 0 value */ AdvanceCounter( TimeCnt, 2 ); /* increments counter value by 2 */ A G R E E M E N T while (i != 1) { GetCounterValue( TimeCnt, &curTime ); /* read TimeCnt value */ if( curTime == CONST ) { /* if desired value, activate TaskB */ ActivateTask( TASK_B ); SetRelAlarm( TimeAlm, 10, 0 ); /* activate TaskX when TimeCnt reaches 10 */ GetAlarm( TimeAlm, &ticksToExpire ); /* just for example: TimeAlm will expire after `ticksToExpire' ticks of TimeCnt */ } if( curTime > CONST )TerminateTask(); /* if more than desired value, terminate the task */ } } N O N - D I S C L O S U R E TASK( Task_B ) { OSMSGNorm _Norm; EventMaskType evMask; evMask = 0x01; InitCounter( DgrCnt, 0 ); /* init degree counter with 0 value */ SetAbsAlarm( DgrAlm, 75, 15 ); /* set cyclic alarm */ WaitEvent( evMask ); /* wait for event which must be set by the alarm */ _Norm = 1; /* wake up and send the message that all is OK */ SendMesssage( Norm, _Norm); TerminateTask(); } ISR( Timer_Isr ) { ... /* reset the hardware */ EnterISR(); CounterTrigger( TimeCnt ); /* increment the counter */ LeaveISR(); } ISR( Dgr_Isr ) { OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Services 241 R E Q U I R E D System Services ... /* reset the hardware */ EnterISR(); CounterTrigger( DgrCnt ); /* increment the counter */ LeaveISR(); } 17.7 Event Management Services The OSEK Operating System establishes the following data types for the event management: * EventMaskType * EventMaskRefType The data type to refer to an event mask. The data type of the event mask; The only data types must be used for operations with events. 17.7.2 Event Declaration To refer to a event the constructional element should be used to declare the event before its using: N O N - D I S C L O S U R E A G R E E M E N T 17.7.1 Data Types Syntax: DeclareEvent( EventMaskType <Event> ) Input: * <Event> - event name. Description: DeclareEvent serves as an external declaration of an event. The function and use of this service are similar to that of the external declaration of variables. Particularities: none Conformance: ECC1, ECC2 User's Manual 242 OSEK Operating System -- Rev 1.2 System Services MOTOROLA Syntax: StatusType SetEvent( TaskType <TaskName>, EventMaskType <Mask> ); Input: * <TaskName> - a reference to the task (the task's name). * <Mask> - an event mask to be set. Output: * None Description: This service is used to set one or several events of the desired task according to the event mask. If the task was waiting for at least one of the specified events, then it is transferred into the ready state. The events not specified by the mask remain unchanged. Only an extended task may be referenced to set an event. Particularities: N O N - D I S C L O S U R E Any events not set in the event mask remain unchanged. It is possible to set events for the running task (task-caller). This service is not implemented if the system configuration option Events or SetEvent are turned off in the configuration file. Status: * * Standard: - E_OK - no error. Extended: - E_OS_ID - E_OS_ACCESS - E_OS_STATE OSEK Operating System -- Rev 1.2 MOTOROLA - the task identifier is invalid; - the referenced task is not an Extended Task; - the referenced task is in the suspended state; User's Manual System Services A G R E E M E N T 17.7.3 SetEvent R E Q U I R E D System Services Event Management Services 243 Conformance: ECC1, ECC2 17.7.4 ClearEvent Syntax: StatusType ClearEvent( EventMaskType <Mask> ); Input: * A G R E E M E N T R E Q U I R E D System Services <Mask> - an event mask to be cleared. Output: * None. Description: The task which calls this service defines the event which has to be cleared. Particularities: The system service ClearEvent is restricted to Extended Tasks. N O N - D I S C L O S U R E This service is not implemented if the system configuration option Events or ClearEvent are turned off in the configuration file. Status: * * Standard: - E_OK - no error. Extended: - E_OS_ACCESS - E_OS_CALLEVEL Conformance: ECC1, ECC2 User's Manual 244 - the calling task is not an Extended Task; - a call at the interrupt level is not allowed. OSEK Operating System -- Rev 1.2 System Services MOTOROLA R E Q U I R E D System Services Event Management Services 17.7.5 GetEvent Syntax: StatusType GetEvent( TaskType <TaskName>, EventMaskRefType <Event> ); Input: * <TaskName> - a reference to the task. * <Event> - a pointer to the event mask to be filled. Description: The event mask which is referenced to in the call is filled according to the current state of the events of the desired task. It is possible to get event mask of the running task (task-caller). Particularities: The referenced task must be an extended task. N O N - D I S C L O S U R E This service is not implemented if the system configuration option Events or GetEvent are turned off in the configuration file. Status: * * Standard: - E_OK - no error. Extended: - E_OS_ID - E_OS_ACCESS - E_OS_STATE Conformance: MOTOROLA - the task identifier is invalid; - the referenced task is not an Extended Task; - the referenced task is in the suspended state; ECC1, ECC2 OSEK Operating System -- Rev 1.2 User's Manual System Services A G R E E M E N T Output: 245 R E Q U I R E D System Services 17.7.6 WaitEvent Syntax: StatusType WaitEvent( EventMaskType <Mask> ); Input: * <Mask> - an event mask to wait for. A G R E E M E N T Output: * None. Description: The calling task is transferred into the waiting state until at least one of the events specified by the mask is set. Particularities: This call enforces the rescheduling, if the wait condition occurs. This service is not implemented if the system configuration option Events or WaitEvent are turned off in the configuration file. N O N - D I S C L O S U R E Status: * * Standard: - E_OK - no error. Extended: - E_OS_ACCESS - E_OS_RESOURCE - E_OS_CALLEVEL Conformance: ECC1, ECC2 User's Manual 246 - the calling task is not an Extended Task; - the calling task occupies resources; - a call at the interrupt level is not allowed. OSEK Operating System -- Rev 1.2 System Services MOTOROLA 17.7.7 Examples of Using Events The example below shows how events can be used in the OSEK Operating System. The following definitions can be made in the definition file (for HC08): N O N - D I S C L O S U R E A G R E E M E N T ... TASK TASK_A { TYPE = EXTENDED; SCHEDULE = FULL; AUTOSTART = TRUE; PRIORITY = 3; StackMethod = OWNSTACK; STACKSIZE = 64; }; TASK TASK_B { TYPE = EXTENDED; SCHEDULE = FULL; AUTOSTART = FALSE; PRIORITY = 3; StackMethod = POOLSTACK; StackPool = POOL1; }; TASK TASK_C { TYPE = BASIC; SCHEDULE = FULL; AUTOSTART = TRUE; PRIORITY = 1; StackMethod = NODESTACK; }; COUNTER DgrCnt { MAXALLOWEDVALUE = 150; TICKSPERBASE = 1; }; ALARM AWAKE { ACTION = SETEVENT; COUNTER = DgrCnt; TASK = TASK_B; EVENT = DgrAlmEvent; }; EVENT DgrAlmEvent { MASK = 0x01; }; MESSAGE Norm { TYPE = QUEUEDMESSAGE; ITEMTYPE = "int"; ITEMS = 6; ReceiverNum = 3; OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Services R E Q U I R E D System Services Event Management Services 247 R E Q U I R E D System Services }; ... The C-language file: #define #define #define #define X_FLG 0x80 Y_FLG 0x40 Z1_FLG 0x20 Z2_FLG 0x10 A G R E E M E N T DeclareTask( TASK_A ) DeclareTask( TASK_B ) DeclareTask( TASK_C ) /* define masks for internal flags */ /* #define may be used for event masks */ /* in other case evnt masks should be */ /* generated by SG tool and established */ /* via DeclareEvent() */ /* the extended tasks */ /* the basic task */ TASK( TASK_A ) /* Extended task TASK_A */ { EventMaskType aa = 3; /* `external' events */ EventMaskType x, z1 = Z1_FLG, /* `internal' events (flags) */ z2 = Z2_FLG; int speed; N O N - D I S C L O S U R E ... /* Check the variable and set internal flag if needed */ if (speed == LIMIT) { x = X_FLG; SetEvent( TASK_A, x ); } ... GetEventMask( TASK_A, &x ); /* check internal flag */ /* Perform some actions in accordance with internal flag status */ if ((x & X_FLG) != 0 ) ClearEvent( z1 ); else SetEvent( TASK_A, z2 ); if ((x & Y_FLG) == 0 ) ChainTask( TASK_C ); ... WaitEvent( aa ); /* the task is stopped until one of three `external' events is set by another task */ ClearEvent( aa ); /* clear all `external' events after awakening */ ... } #define EVMASK1 #define EVMASK2 #define EVMASK3 0x01 0x02 0x04 /* event mask definitions */ User's Manual 248 OSEK Operating System -- Rev 1.2 System Services MOTOROLA TASK( TASK_B ) /* Extended task TASK_B */ { EventMaskType b_ev, a_ev; b_ev = EVMASK1 | EVMASK3; InitCounter( DgrCnt, 10 ); /* initialize the counter */ ... SetRelAlarm( AWAKE, 20, 0 ); /* this alarm will awake the task */ WaitEvent( b_ev ); /* waiting for one of two events */ ClearEvent( b_ev ); /* clear all events */ GetEvent( TASK_A, &a_ev ); /* get events of TASK_A */ if ( (a_ev & EVMASK2) == 0) { a_ev = EVMASK2; SetEvent( TASK_A, a_ev ); } /* set the event for TASK_A */ ... } TASK( TASK_C ) /* Basic task TASK_C */ { EventMaskType bb, set; set = EVMASK3; ... GetEventMask( TASK_B, &bb ); /* if the event is clear, set it */ if ((bb & EVMASK3) == 0 ) SetEvent( TASK_B, set ); ... } 17.8 Communication Management Services 17.8.1 Data Types and Identifiers The following names are used in the OSEK Operating System for work with messages: * SymbolicName This is an unique name representing a message. It only can be used in conjunction with calls of the message OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Services 249 N O N - D I S C L O S U R E A G R E E M E N T /* The task will be ready again when one of two events are set. One of them - EVMASK1 will be set by the alarm AWAKE after 20 ticks of the counter DgrCnt. Thus, the task can delay itself. */ R E Q U I R E D System Services Communication Management Services R E Q U I R E D System Services service. A SymbolicName need not be a data type. Variables or constants of SymbolicName can be declared or used. AccessName N O N - D I S C L O S U R E A G R E E M E N T * This is a unique name defining access to a message object. Depending on the chosen configuration, a distinction is made between the following AccessName scheme: WithCopy configuration: A application variable exists as a local copy of the message. The name of the variable is the AccessName. This variable contains a copy of the corresponding message object. WithoutCopy configuration: The message object data is accessed via the AccessName. This AccessName is a static link: it refers directly to the message object data. The AccessName refers to the same data (RAM) as the message object. 17.8.2 SendMessage Syntax: StatusType SendMessage ( SymbolicName <Message>, AccessName <Data> ) Input: * <Message> - symbolic name of the message object, * <Data> - AccessName of the message data to be sent. Output: * None. User's Manual 250 OSEK Operating System -- Rev 1.2 System Services MOTOROLA In case of WithCopy: This service updates the message object <Message> with the Data given by <Data> and requests the transmission of the message object to the receiving entities. The message object is locked during this update and during the transmission of the data to the underlying communication layer. The message object is not updated if it is already locked. This service updates also the status information of the message object accordingly. In case of WithoutCopy: - Possible for unqueued message type only - This service requests the transmission of the already updated message object to the receiving entities via the bus. Particularities: SendMessage does not verify whether the message object has been initialized prior to sending it. Status: * Standard: WithCopy - E_OK - E_COM_LOCKED - message object updated, - message object locked. WithoutCopy - E_OK - E_COM_LOCKED - successful operation, - message object locked. Extended: - E_COM_ID - invalid parameter <Message>. Conformance: N/A OSEK Operating System -- Rev 1.2 MOTOROLA N O N - D I S C L O S U R E * User's Manual System Services A G R E E M E N T Description: R E Q U I R E D System Services Communication Management Services 251 R E Q U I R E D System Services 17.8.3 ReceiveMessage Syntax: StatusType ReceiveMessage ( SymbolicName <Message>,AccessName <Data>) Input: * <Message> - symbolic name of the message object. A G R E E M E N T Output: * <Data> - AccessName of the message data to be received Description: In case of WithCopy: This service delivers the message data associated with the message object <Message> to the applications message copy referenced by <Data>. The message object is locked during data reception. This service also updates the status information of the message object accordingly. N O N - D I S C L O S U R E In case of WithoutCopy: - Possible for unqueued message type only - Returns Status only since application can access directly to the message object. Particularities: Queued messages: 1. The service returns the oldest message. 2. In case of a FIFO overflow, at leas t one message was lost, the oldest message is returned. 3.If the FIFO is empty, no message is returned to the application. Unqueued messages: 1. The service returns the current message. 2. If no new message has been received since the last call to ReceiveMessage the current message is returned. User's Manual 252 OSEK Operating System -- Rev 1.2 System Services MOTOROLA Standard: WithCopy: - E_OK - E_COM_LOCKED - E_COM_NOMSG - E_COM_NOMSG - E_COM_LIMIT WithoutCopy: - E_OK - E_COM_LOCKED * - message available, - message object locked, - in case of unqueued message, no message received so far, - in case of queued message, no message available (FIFO empty), - at least one message has been lost for a message object. - successful operation, - message object locked. Extended: - E_COM_ID- invalid parameter <Message>. Conformance: N/A 17.8.4 GetMessageResource Syntax: StatusType GetMessageResource ( SymbolicName <Message> ) Input: * <Message> - symbolic name of the message object. Output: * None. Description: The service GetMessageResource sets the given message object <Message> status (extended: for other tasks) as busy if it is not already so. This call serves to enter critical sections in the code that are assigned OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Services 253 A G R E E M E N T * N O N - D I S C L O S U R E Status: R E Q U I R E D System Services Communication Management Services R E Q U I R E D System Services to read or write the message object referenced by <Message>. A critical section (critical sections should be short) must always be left using ReleaseMessageResource. Particularities: This service provides message availability information for the application to ensure message consistency between API communication service calls in the without copy configuration. N O N - D I S C L O S U R E A G R E E M E N T Corresponding calls to Get- and ReleaseMessageResource should appear within the same function on the same function level. Before terminating the task or entering the wait or suspend state the corresponding service ReleaseMessageResource has to be used. Status: * * Standard: - E_OK - E_COM_BUSY - message object is set busy , - message object is already busy. Extended: - E_COM_ID - invalid parameter <Message>. Conformance: N/A 17.8.5 ReleaseMessageResource Syntax: StatusType ReleaseMessageResource ( SymbolicName <Message> ) Input: * <Message> - symbolic name of the message object. Output: * None. User's Manual 254 OSEK Operating System -- Rev 1.2 System Services MOTOROLA Description: The service ReleaseMessageResource sets off the message object <Message> from busy. ReleaseMessageResource is the counterpart of GetMessageResource and serves to leave critical sections in the code that are assigned to read or write the message object referenced by <Message>. Particularities: A G R E E M E N T This service allows for message consistency to be ensured by the application in case without copy configuration. Corresponding calls to Get- and ReleaseMessageResource should appear within the same function on the same function level. Before terminating the task or entering the wait or suspend state the corresponding service ReleaseMessageResource has to be used Status: * Standard: - E_OK - message object unlocked successfully. Extended: - E_COM_ID Conformance: - invalid parameter <Message>. N O N - D I S C L O S U R E * N/A 17.8.6 GetMessageStatus Syntax: StatusType GetMessageStatus ( SymbolicName <Message> ) Input: * <Message> - symbolic name of the message object Output: * None. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Services R E Q U I R E D System Services Communication Management Services 255 R E Q U I R E D System Services Description: The service GetMessageStatus returns the current status of the message object <Message>. If this service call fails, it has to return an implementation specific error code which can be distinguished from all other return values. Particularities: N O N - D I S C L O S U R E A G R E E M E N T None. Status: * Standard: - E_OK - E_COM_BUSY - E_COM_LOCKED - E_COM_NOMSG - E_COM_NOMSG - no error, - message object is currently in use by the application, - message object locked irrespective of whether the message object is currently in use by the application (busy), - in case of unqueued message, no message received so far, - in case of queued message, no message available, - E_COM_LIMIT - at least one message has been lost, - implementation specific status information or error codes. * Extended: - E_COM_ID Conformance: - invalid parameter <Message>. N/A 17.8.7 Examples of Using Messages The examples below present the usage of system services for communication. The Unqueued Message MsgBAst has a timestamp and it is defined as a message of the MSGTS type. The following definitions can be made in the definition file (for HC08): User's Manual 256 OSEK Operating System -- Rev 1.2 System Services MOTOROLA R E Q U I R E D System Services Communication Management Services N O N - D I S C L O S U R E A G R E E M E N T ... TASK TASK_A { TYPE = EXTENDED; SCHEDULE = FULL; AUTOSTART = FALSE; PRIORITY = 3; StackMethod = POOLSTACK; StackPool = POOL1; }; TASK TASK_B { TYPE = BASIC; SCHEDULE = FULL; AUTOSTART = TRUE; PRIORITY = 2; EntryPoint = "task_b"; StackMethod = OWNSTACK; STACKSIZE = 64; }; TASK TASK_X { TYPE = BASIC; SCHEDULE = FULL; AUTOSTART = TRUE; PRIORITY = 1; StackMethod = NODESTACK; }; COUNTER Post { MAXALLOWEDVALUE = 24; TICKSPERBASE = 1; }; MESSAGE msgAAst { TYPE = UNQUEUEDMESSAGE; ITEMTYPE = "int"; ITEMS = 1; WithCopy = FALSE; }; MESSAGE msgBAst { TYPE = UNQUEUEDMESSAGE; ITEMTYPE = "MSGTS"; ITEMS = 1; WithCopy = TRUE; }; MESSAGE msgCBst { TYPE = UNQUEUEDMESSAGE; ITEMTYPE = "int"; ITEMS = 1; WithCopy = TRUE; }; MESSAGE msgDBev { TYPE = QUEUEDMESSAGE; ITEMTYPE = "int"; OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Services 257 R E Q U I R E D System Services ITEMS = 6; ReceiverNum = 3; }; ... The C-language code can be the following: DeclareTask( TASK_A ) DeclareTask( TASK_B ) DeclareTask( TASK_X ) A G R E E M E N T OSMSGmsgAAst OSMSGmsgBAst OSMSGmsgCBst OSMSGmsgDBev *_msgAAst = &OSmsgAAst; _msgAAst; _msgCBst; _msgDBev; DeclareCounter( Post ) typedef struct tagMSGTS MSGTS; struct tagMSGTS { TickType ts; int x; }; N O N - D I S C L O S U R E void Func( void ); { /* The function uses the Queued Message - receives and processes it */ ReceiveMessage( msgDBev ); ... } TASK( TASK_A ) { ... ReceiveMessage( msgCBst, _msgCBst ); /* get the message */ if( msgCBst == 2 ) *_msgAAst = 1; else *_msgAAst = 33; SendMessage( msgAAst, _msgAAst ); ... _msgBAst.x = 60; GetCounterValue( Post, &(_msgBAst.ts) ); SendMessage( msgBAst, _msgBAst ); ... Func(); ... } TASK( TASK_B ) User's Manual 258 OSEK Operating System -- Rev 1.2 System Services MOTOROLA ReceiveMessage( msgBAst, _msgBAst ); _msgBAst.ts = 60; GetCounterValue( Post, &cur_time ); if( (cur_time - _msgBAst.ts) > 15 ) SetEvent( TASK_X, 1 ); ... SendMessage( msgEBev, _msgEBev ); ... } 17.9 Operating System Execution Control 17.9.1 Data Types The OSEK OS establishes the following data type for operation mode representation: * AppModeType This data type represents the operating mode. 17.9.2 GetActiveApplicationMode Syntax: AppModeType GetActiveApplicationMode( void ); Description: This service returns the current application mode. It may be used to write mode dependent code (see Section 11.6 Application Modes). This service is not implemented if the system configuration option GetActiveApplicationMode is turned off in the configuration file. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Services 259 N O N - D I S C L O S U R E { TickType cur_time; ... _msgCBst = 15; SendMessage( msgCBst, _msgCBst ); ... ReceiveMessage( msgAAst, _msgAAst ); if( *_msgAAst == 1 ) ActivateTask( TASK_X ); A G R E E M E N T R E Q U I R E D System Services Operating System Execution Control R E Q U I R E D System Services Particularities: Conformance: BCC1, BCC2, ECC1, ECC2 17.9.3 StartOS Syntax: void StartOS( AppModeType <Mode> ); A G R E E M E N T Input: * <Mode> - operating mode. Output: * None. Description: The user can call this system service to start the system in a specific mode. This service calls user hook StartupHook. Each application mode consists of own set of tasks (see Section 11.6 Application Modes). N O N - D I S C L O S U R E Particularities: See Section 11.5 Start-up Routine and Section 11.6 Application Modes for general description of system startup. Conformance: BCC1, BCC2, ECC1, ECC2 17.9.4 ShutdownOS Syntax: void ShutdownOS( StatusType <Error> ); Input: * <Error> - a code of the error occurred. Output: * None. User's Manual 260 OSEK Operating System -- Rev 1.2 System Services MOTOROLA Description: The user can call this system service to abort the overall system (e.g. emergency off). The operating system also calls this function internally, if it has reached an undefined state and is no longer ready to run. This service calls user hook ShutdownHook. If ShutdownHook returns, the operating system jumps to the next statement following the initial call to StartOS (see Section 11.7 System Shutdown). R E Q U I R E D System Services Operating System Execution Control ShutdownOS is application specific, since standardized error treatment is not possible. ShutdownOS runs in connection with the currently active context, which may be unknown to the user. Thus, no API functions are admitted within the ShutdownOS routine. After the return from ShutdownOS service all interrupts will be disabled. This service is not implemented if the system configuration option ShutdownOS is turned off in the configuration file. Conformance: BCC1, BCC2, ECC1, ECC2 17.9.5 Examples of Application Modes Usage The example bellow demonstrates different application modes usage. The following definitions can be made in the definition file (for HC08): OIL_VERSION = "2.0e"; /* Force SG to use Extended */ /* OIL format */ INCLUDE "mot20.oil" CPU cpu1 { CFGACTIVE = { ModeA, ModeB }; .... CFG ModeA { TASK TC { TYPE = EXTENDED; /* Application mode "ModeA" */ /* Common task for both modes */ OSEK Operating System -- Rev 1.2 MOTOROLA /* Two application modes */ /* "ModeA", "ModeB" are */ /* defined */ User's Manual System Services 261 N O N - D I S C L O S U R E ShutdownOS never returns to the location where it was called. A G R E E M E N T Particularities: R E Q U I R E D System Services SCHEDULE = FULL; AUTOSTART = TRUE; StackMethod = OWNSTACK; STACKSIZE = 60; PRIORITY = 3; A G R E E M E N T }; TASK TA1 { /* ModeA specific task TA1 */ TYPE = BASIC; SCHEDULE = FULL; AUTOSTART = TRUE; StackMethod = POOLSTACK; StackPool = POOL; PRIORITY = 2; }; ... /* Other ModeA tasks */ N O N - D I S C L O S U R E }; CFG ModeB { /* Application mode "ModeB" */ TASK TB1 { /* ModeB specific task TB1 */ TYPE = BASIC; SCHEDULE = FULL; AUTOSTART = TRUE; StackMethod = POOLSTACK; StackPool = POOL; PRIORITY = 4; }; TASK TC { /* Common task for both modes */ TYPE = EXTENDED; SCHEDULE = FULL; AUTOSTART = TRUE; StackMethod = OWNSTACK; STACKSIZE = 60; PRIORITY = 5; }; ... /* Other ModeB tasks */ }; STACK POOL { /* Stack pool definition */ StackSize = 60; NumberOfStacks = 3; } COUNTER Timer { ... };/* Counter definition */ ALARM TimeLimit { /* Alarm definition */ ACTION = SETEVENT; COUNTER = Timer; TASK = TC; /* Activates common task */ EVENT = SHUTDOWN; } EVENT SHUTDOWN { MASK = 0x01; }; EVENT STARTTA1 { MASK = 0x02; }; EVENT STARTTB1 { MASK = 0x04; }; .... }; User's Manual 262 OSEK Operating System -- Rev 1.2 System Services MOTOROLA The C-language code can be the following: /* /* /* /* /* /* /* /* ModeA specific task TA1 */ ModeB specific task TB1 */ Task TC is shared between both modes */ System timer */ Alarm to abort the system */ TC command: shutdown the system */ TC command: activate TA1 */ TC command: activate TB1 */ /* Set initial application mode */ /* /* StartOS( NewMode ); ... /* /* Perform some actions before startup*/ and start OS in specific mode */ Perform some actions after system*/ shutdown */ } } TASK( TC ) /* TC code is shared between both modes */ { EventMaskType tc_ev; /* Set maximum possible time limit */ SetRelAlarm( TimeLimit, 1000, 0 ); for( ; ; ) { ClearEvent( SHUTDOWN|STARTTA1|STARTTB1 ); WaitEvent( SHUTDOWN|STARTTA1|STARTTB1 ); GetEvent( TC, &tc_ev ); if( ( tc_ev & SHUTDOWN ) != 0 ) { /* Force system shutdown */ ShutdownOS( E_OK ); } if( ( tc_ev & STARTTA1 ) != 0 ) { /* Activate ModeA specific task */ ActivateTask( TA1 ); } if( ( tc_ev & STARTTB1 ) != 0 ) { /* Activate ModeB specific task */ ActivateTask( TB1 ); } } } /* USer's shutdown hook */ void ShutdownHook( StatusType Error ) OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Services 263 A G R E E M E N T /* Application mode */ N O N - D I S C L O S U R E DeclareTask( TA1 ) DeclareTask( TB1 ) DeclareTask( TC ) DeclareCounter( Timer ) DeclareAlarm( TimeLimit ) DeclareEvent( SHUTDOWN ) DeclareEvent( STARTTA1 ) DeclareEvent( STARTTB1 ) ... AppModeType NewMode; void main( void ) { NewMode = ModeA; for( ; ; ) { ... R E Q U I R E D System Services Operating System Execution Control { /* Check current application if( GetActiveApplicationMode( ) = ModeA ) NewMode = ModeB; /* Next time the system will /* in application mode ModeB else NewMode = ModeA; /* Next time the system will /* in application mode ModeA mode */ start */ */ start */ */ } TASK( TA1 ) { ... TerminateTask( ); } TASK( TB1 ) { ... TerminateTask( ); } /* ModeA specific task */ /* Activate other ModeA specific tasks */ /* And terminate self */ /* ModeB specific task */ /* Activate other ModeB specific tasks */ /* And terminate self */ 17.9.6 Hook Routines 17.9.6.1 ErrorHook Syntax: N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D System Services void ErrorHook( StatusType <Error> ); Input: * <Error> - a code of the error occurred. Output: * None. Description: This hook is called by the operating system at the end of a system service which has a return value not equal to E_OK. It is called before returning to the call level. For error parameters to be transferred see Section 17.9.4 ShutdownOS. User's Manual 264 OSEK Operating System -- Rev 1.2 System Services MOTOROLA R E Q U I R E D System Services Operating System Execution Control Particularities: See Section 11.3 Hook Routines for general description of hook routines. This hook is not implemented if the system configuration option ErrorHook is turned off in the configuration file. Status: Conformance: A G R E E M E N T None. BCC1, BCC2, ECC1, ECC2 17.9.6.2 PreTaskHook Syntax: void PreTaskHook( void ); Input: * None. Output: * None. Description: This hook is called before the operating system enters the context of the task. This hook is called from the scheduler when it passes control to the given task. It may be used by the application to trace the sequences and timing of tasks' execution. Particularities: See Section 11.3 Hook Routines for general description of hook routines. This hook is not implemented if the system configuration option PreTaskHook is turned off in the configuration file. Status: OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Services 265 N O N - D I S C L O S U R E * None. Conformance: N O N - D I S C L O S U R E BCC1, BCC2, ECC1, ECC2 17.9.6.3 PostTaskHook Syntax: void PostTaskHook( void ); Input: A G R E E M E N T R E Q U I R E D System Services * None. Output: * None. Description: This hook is called after the operating system leaves the context of the task. This hook is called from the scheduler when it switches from the current task to another. It may be used by the application to trace the sequences and timing of tasks' execution. Particularities: See Section 11.3 Hook Routines for general description of hook routines. This hook is not implemented if the system configuration option PostTaskHook is turned off in the configuration file. Status: None. Conformance: BCC1, BCC2, ECC1, ECC2 17.9.6.4 IdleLoopHook Syntax: void IdleLoopHook( void ); User's Manual 266 OSEK Operating System -- Rev 1.2 System Services MOTOROLA * None. Output: * None. Description: This hook is called by the operating system from scheduler idle loop. It is not possible to call OSEK OS directives from this hook. Hardware dependent code like manipulation with COP registers may be placed here. Particularities: See Section 11.3 Hook Routines for general description of hook routines. This hook is not implemented if the system configuration option IdleLoopHook is turned off in the configuration file. Conformance: BCC1, BCC2, ECC1, ECC2 17.9.6.5 StartupHook Syntax: void StartupHook( void ); Input: * None. Output: * None. Description: This hook is called by the operating system at the end of the operating system initialization and before the scheduler is running. At this point in time the application can start tasks, alarms, initialize device drivers etc. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Services 267 N O N - D I S C L O S U R E Input: A G R E E M E N T R E Q U I R E D System Services Operating System Execution Control R E Q U I R E D System Services Particularities: See Section 11.3 Hook Routines for general description of hook routines. This hook is not implemented if the system configuration option StartupHook is turned off in the configuration file. Status: Conformance: BCC1, BCC2, ECC1, ECC2 17.9.6.6 ShutdownHook Syntax: void ShutdownHook( StatusType <Error> ); Input: * <Error> - a code of the error occurred. Output: * N O N - D I S C L O S U R E A G R E E M E N T None. None. Description: This hook is called by the operating system when the service ShutdownOS has been called. This routine is called before the operating system shuts down itself. Particularities: See Section 11.3 Hook Routines for general description of hook routines. This hook is not implemented if the system configuration option ShutdownHook is turned off in the configuration file. Status: None. Conformance: BCC1, BCC2, ECC1, ECC2 User's Manual 268 OSEK Operating System -- Rev 1.2 System Services MOTOROLA 18.2 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .269 18.3 ORTI Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .271 18.5 ORTI Generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .275 18.2 General The purpose of OSEK Run Time Interface (ORTI) implementation is giving the user extended opportunities in debugging embedded OSEK applications. The ORTI shall be supported from both sides: an OSEK OS and a debugger. The debugger able to display information in terms of OSEK system objects is "OSEK aware" debugger. The internal OS data is to be made available to the debugger. For this purpose special ORTI file is generated at configuration time by an ORTI generator. As a result, more services will be available to the user during application debugging session. The ORTI generator (OrtiGen) is the command line utility which uses OIL file (App.oil) as input file. The OrtiGen utility generates static information in the ORTI format. This utility analyzes the application configuration and generates ORTI file. The same OIL file is processed by the SysGen and all files with configuration data for OS are generated. After application is compiled and linked and executable and map files are created then they are loaded by the debugger. If the debugger is OSEK aware then it can load also the ORTI file for this application. The information from ORTI file provide the debugger with possibility to display information about system objects of current implementation of OSEK OS. This process is depicted on Figure 18-1. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual ORTI Implementation 269 R E Q U I R E D 18.1 Contents A G R E E M E N T Section 18. ORTI Implementation N O N - D I S C L O S U R E User's Manual -- OSEK Operating System R E Q U I R E D ORTI Implementation User's Source File app.c OS OIL File A G R E E M E N T SysGen OrtiGen Application Configuration Files Compiler/Linker N O N - D I S C L O S U R E Executable File MAP File ORTI File OSEK Aware Debugger OSEK Operating System components: Data files Programs Third-party tools Library Figure 18-1. Application Building Process with ORTI Support User's Manual 270 OSEK Operating System -- Rev 1.2 ORTI Implementation MOTOROLA * Trace interface, which means getting an access to the data on a running target when it is essential to trace data changes in a real time; * Breakpoint interface, which provides an access to desirable data on a stopped target. Note that ORTI Trace interface is designed to provide access to requested data in accomplished form that is not requiring additional processing. 18.3.1 ORTI Trace Interfaces There are two trace ORTI interfaces: running task identification in runtime and OSEK OS system calls identification in run-time. The special attributes are generated for the OS object in ORTI file to support trace interfaces. There are RUNNINGTASK and CURRENTSERVICE attributes1. * RUNNINGTASK This attribute specifies the name of the currently running task within the OS. The RUNNINGTASK attribute value presents the address of a byte which contains either byte numeric identifier of a task which is currently in the running state or the special byte value in case of none tasks are in the running state. The certain values of task identifiers are statically determined and enumerated in the type field of RUNNINGTASK attribute of an OS object as well as the special value (NO_TASK) representing none of tasks running. 1. These attributes are specified in the document "ORTI: OSEK Run Time Interface, Version 2.0 (Draft a), 18 February 1999". OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual ORTI Implementation 271 A G R E E M E N T ORTI provides two kinds of interfaces to OSEK OS data: N O N - D I S C L O S U R E 18.3 ORTI Features R E Q U I R E D ORTI Implementation ORTI Features R E Q U I R E D ORTI Implementation The value of the RUNNINGTASK attribute is updated each time CPU switches to another task or to the code corresponding to none of task running. * CURRENTSERVICE This attribute specifies which operating service, if any is currently being executed. A G R E E M E N T The CURRENTSERVICE attribute value presents the address of a byte which represents a service numeric identifier. This value is updated with OSEK OS service (Service) identifier on the following events occurred: - CPU enters Service code; - CPU resumes execution of Service code after switching to the task preempted (this also could take place in case of unacted task preemption, when system scheduler tried to switch to another task but found no appropriate task to switch to and resumed Service code execution in a frame of the current task); - CPU resumes execution of Service code after leaving nested OSEK OS service call (mainly for hook services). N O N - D I S C L O S U R E In case of leaving OSEK OS service the byte accepts the special value (NO_SERVICE) corresponding to none of OSEK OS service being currently executed. The byte is updated with this value on the following events occurred: - CPU leaves OSEK OS service code and starts to execute non OSEK OS service code; - CPU preempts execution of OSEK OS service code to perform task switching. NOTE: Typically trace sequence of CURRENTSERVICE looks like the following: Traced Value Description ... SERVICE_1_ID entering or resuming Service 1 NO_SERVICE leaving Service 1 (possibly due to task switching) User's Manual 272 OSEK Operating System -- Rev 1.2 ORTI Implementation MOTOROLA Description ... SERVICE_2_ID entering or resuming Service 2 SERVICE_2_ID resuming Service 2 execution after unacted task preemption (could be ignored) NO_SERVICE leaving Service 2 (possibly due to task switching) ... SERVICE_3_ID entering or resuming Service 3 SERVICE_4_ID entering nested Service 4 call (possibly hook routine) SERVICE_3_ID leaving Service 4 and resuming Service 3 NO_SERVICE leaving Service 3 (possibly due to task switching) ... SERVICE_5_ID entering or resuming Service 5 SERVICE_6_ID entering nested Service 6 call (possibly hook routine) NO_SERVICE leaving Service 5 and Service 6 (possibly due to task switching) A G R E E M E N T Traced Value R E Q U I R E D ORTI Implementation ORTI Features 18.3.2 ORTI Breakpoint Interface There is one Breakpoint ORTI interface intended to facilitate debugger access to task related data. The following static (at breakpoints) ORTI services are supported: * access to tasks information for a debugger on breakpoints; * access to stacks information for a debugger on breakpoints. Information needed to display the current task status is available for the debugger whenever the debugger is stopped (i.e. this information is not required in real-time and hence can be read from the TCB or similar structure). OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual ORTI Implementation 273 N O N - D I S C L O S U R E ... R E Q U I R E D ORTI Implementation The following task information is available to the user: priority, * current stack. Information in the ORTI file allows a debugger to display task information using values that the user sets in the OIL file. The task priority value is provided with taking into account possible task priority changes due to a dynamic resource allocation. A G R E E M E N T N O N - D I S C L O S U R E * The task state indicates a standard OSEK state the task is currently in. Information needed to display stacks allocated in the system is available for the debugger whenever the debugger is stopped. All memory areas defined as stack in the application are presented via: NOTE: ... +seg +def +spc +def ... * size, * start address. To provide system with information about application main stack area make sure 2 variables are defined in Cosmic link command file: __stack (required for Cosmic start-up code) and __stackstart (should be allocated at the lowest address byte of application main stack area). In this case Cosmic link command file may look like the following: .bss -a data __stackstart=@.bss .bss=0x3F __stack=@.bss # # # # BSS starts after .data pointer to stack start value reserve 0x3f bytes for stack in BSS stack pointer value 18.4 ORTI Supporting OS Properties To control ORTI support some additional attributes should be defined in the configuration file (OIL file). The following attributes are specified for an object of the OS type: User's Manual 274 OSEK Operating System -- Rev 1.2 ORTI Implementation MOTOROLA * ORTIRunningTask (BOOLEAN) Specifies that the running task identification in run-time support will be used. This attribute will be ignored if DEBUG_LEVEL = 0. * ORTICurrentService (BOOLEAN) Specifies that the OSEK OS system calls identification in run-time support will be used. This attribute will be ignored if DEBUG_LEVEL = 0. All attributes of the OS object are described in Section 13.3 OS Definition. 18.5 ORTI Generator The ORTI generator utility is a command line utility which has the OIL file as input and ORTI file as result of work. The ORTI generation utility is intended to prepare all data needed for OSEK aware debugger to display information about application in OSEK terms. The OrtiGen utility has the following format of command line: ortigen [-options] filename All options are case sensitive. The space between option and argument is optional. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual ORTI Implementation 275 A G R E E M E N T DEBUG_LEVEL (ENUM) Specifies the ORTI support in OS. The attribute can have values 0 or 1. If the system has the DEBUG_LEVEL = 0 the static ORTI support is switched off. If the system has the DEBUG_LEVEL = 1 this mode is considered to be a debugging mode. N O N - D I S C L O S U R E * R E Q U I R E D ORTI Implementation ORTI Generator R E Q U I R E D ORTI Implementation The following options are accepted by the OrtiGen: Table 18-1. ORTI Generator Command Line Options A G R E E M E N T Option Description -c The argument of this option defines file name for output ORTI file. By default the input file name with extension .ort is used -i This option adds a directory to the list of directories searched for include files. To search more than one directory, give additional -i options on the command line - one -i option for each directory. Directories are searched only until the specified include file is found -n The argument of this option defines CPU name for which the ORTI file will be written. By default the first CPU in the file is used -t The argument of this option defines the name of template file for the ORTI file generation The location of the ORTI template file can be pointed either in command line or via the ORTI_TEMPLATE environment variable. In addition to command line option the OSB_INCLUDE_DIR environment variable can be used to specify the set of directories. N O N - D I S C L O S U R E If the ORTI generator finds an error in the source files, it either halts processing or outputs a warning message depending on the error severity. If there are no error, the OrtiGen returns 0, if there are mild errors the OrtiGen sends warning messages and returns 0, but does not terminate processing, if severe errors are detected - the OrtiGen returns 2 and does not produce output file. The ORTI generator performs the same verification as the SysGen does and has the same format of error messages. All System Generator error and warning messages and their formats are described in Appendix D System Generation Error Messages. If the DEBUG_LEVEL attribute of the OS object is set to 0 or undefined in the OIL file then the ORTI file is not produced and the following warning is generated: W0010: DEBUG_LEVEL is undefined, ORTI file is not generated If the DEBUG_LEVEL attribute is undefined in the implementation definition then the following warning is generated: User's Manual 276 OSEK Operating System -- Rev 1.2 ORTI Implementation MOTOROLA R E Q U I R E D ORTI Implementation ORTI Generator N O N - D I S C L O S U R E A G R E E M E N T W0011: DEBUG_LEVEL is not defined in implementation OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual ORTI Implementation 277 N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D ORTI Implementation User's Manual 278 OSEK Operating System -- Rev 1.2 ORTI Implementation MOTOROLA A.2 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .279 A.3 Source Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .280 A.2 Description The Sample application delivered with the OSEK Operating System should help to learn how to use OSEK OS. The Sample's source files are located in the SAMPLE directory - it contains all files needed to create an executable file. The Sample is not a real application and it does not perform any useful work. But it has a certain algorithm so it is possible to track the execution. It uses most of OSEK OS mechanisms and allows the user to have the first look inside the OSEK OS. The Sample consists of four tasks. It uses two counters (one of them is the standard OSEK OS timer), three alarms, one resource, one unqueued and one queued message. Timer interrupt is handled by the ISR. Generally, Sample tasks are divided into two pairs. TASKSND and TASKRCV compose the first pair and TASKPROD, TASKCONS are the second pair. This two pairs interacts with the help of the event mechanism. The task TASKSND is activated by the StartOS routine. It gets the resource to provide exclusive access to the unqueued message MsgA, modifies the message and sends it to TASKRCV. After that the resource is released and the task terminates itself. MsgA consists of two parts (it has the user defined type) and only one part (`value' is changed by OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Sample Application 279 R E Q U I R E D A.1 Contents A G R E E M E N T Appendix A. Sample Application N O N - D I S C L O S U R E User's Manual -- OSEK Operating System R E Q U I R E D Sample Application TASKSND). The message is used without copying. Arrival of the message activates the task TASKRCV. TASKRCV receives the message MsgA and analyzes it. If the `value' is greater than the certain limit, the second part of MsgA is increased and the event is set for the task TASKPROD (producer). In the end the task releases the resource and terminates itself. N O N - D I S C L O S U R E A G R E E M E N T The task TASKPROD is activated by the StartOS routine. Just after the activation the task activates the system counter (timer) and the counter for messages and sets two alarms. To prevent rescheduling at this moment the scheduler is got by the tasks as a standard resource. One alarm is the relative cyclic alarm based on the system timer, it will be used to "awake" the task, and the second alarm is the absolute alarm based on the message counter. The message counter is intended to count the number of items in the queued message MsgB. After all initialization activities TASKPROD calls the WaitEvent service and, thus, the task delays itself. When TASKPROD becomes running again, it sends the queued message MsgB. The message contents depends on the event which has caused task awakening. After sending MsgB the message counter is triggered. The task TASKCONS (consumer) has the lowest priority. This is preemptive task. TASKCONS is activated by the alarm when the message counter reaches the predefined number. The task reads (consumes) queued message MsgB items and analyzes them. In case of the "S_OK" message the message timestamp is saved in the variable "normal". In case of the "S_LIMIT" message the period of time elapsed between the "S_OK" and "S_LIMIT" messages is saved in the variable "period". The user can watch the "normal" and "period" variables, the message contents and so on. A.3 Source Files Source files for the Sample application are the following: * "sample.c" - the application code, User's Manual 280 OSEK Operating System -- Rev 1.2 Sample Application MOTOROLA * "makefile" - command files to build the executable file, * "vector.c"- Vector table, * "crts.s" - Start-up module for Cosmic * "make.bat" - Environment Configuration file for OSEK OS (builds executable file) To build the executable file the user should make sure that OSEK OS components are properly installed on the disk and pathes for the OSEK directory and compiler software are known. The makefile was written for Microsoft Visual C++ 4.2 NMAKE utility. Run the MAKE.BAT to build the executable file. To build sample application for Cosmic compiler run MAKE.BAT with 'c' variable set to 'cosmic12': >MAKE "c=cosmic12" To build sample application for M68HC12B32EVB run MAKE.BAT with 'type' variable set to 'B32': >MAKE "type=B32" To build sample application for M68HC12D60EVB user should run MAKE.BAT with 'type' variable set to 'D60': >MAKE "type=D60" To clean all produced files in the OSEK\SAMPLE directory user should run MAKE.BAT and set clean target: >MAKE clean (See the file "makefile" in the OSEK\SAMPLE directory for additional information) Makefile uses the system environment variables CXPATH, CXLIB and OSEKDIR to get Cosmic and OSEK components. When all produced filed are ready, the executable file can be load into the Evaluation board (HC12D60EVB for example) and run. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Sample Application 281 A G R E E M E N T "cfg20.oil" - OSEK Implementation Language file (Version 2.0), N O N - D I S C L O S U R E * R E Q U I R E D Sample Application Source Files N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Sample Application User's Manual 282 OSEK Operating System -- Rev 1.2 Sample Application MOTOROLA Appendix B. System Service Timing B.1 Contents B.2 General Notes The following notation is used to define four main states for run-time services: * Immediate Response (IR) - The service completes immediately without any tasking changes. * Stop Task (ST) - The service transfers the task from the running state into another state (ready, waiting or suspended). Task switching will take place. * Task Waiting (TW) - The service called transfer another task into the ready state (from waiting or suspended states). This task has the same or lower priority than the task calling the service, or preemption is disabled, therefore task switching will not take place. * Task Waiting and Context Switching (TWCS) - The service called transfer another task into the running state (from ready, waiting or suspended states). This task has the higher priority than the calling task, therefore task switching is performed. Results in Table B-1 and Table B-2 below was got on the basis of the certain OS configuration. The list of systetm properties is shown below, and this configuration is called in the table as "Initial". Properties that are not listed have their default values. In the column "Condition" the differences from the given list ("Initial") are indicated. For each configuration the corresponded numbers are provided in the table. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Service Timing 283 A G R E E M E N T General Notes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .283 N O N - D I S C L O S U R E B.2 R E Q U I R E D User's Manual -- OSEK Operating System R E Q U I R E D System Service Timing OIL_VERSION = "2.0"; #include "mot20.oil" N O N - D I S C L O S U R E A G R E E M E N T CPU cpu1 { OS os1 { OSVERSION = 2; TargetMCU = HC12; CC = BCC2; EntryExitISR = TRUE; InterruptMaskControl = TRUE; SCHEDULE = FULL; TaskIndexMethod = FALSE; StackPool = FALSE; TaskOwnStack = TRUE; PersistentNode = TRUE; PersistentStack = FALSE; STATUS = EXTENDED; ErrorHook = TRUE; StartupHook = TRUE; ShutdownHook = TRUE; PreTaskHook = FALSE; PostTaskHook = FALSE; InternalErrorHandler = TRUE; Resources = FALSE; FastResource = FALSE; Events = FALSE; Counters = TRUE; CounterSize = 32; Alarms = TRUE; AlarmList = TRUE; UnqueuedMessages = TRUE; UnqueuedMsgDefaultValue = TRUE; QueuedMessages = FALSE; QueuedMsgOneToN = FALSE; ActivateOnMsg = FALSE; AlarmOnMsg = FALSE; SetEventOnMsg = FALSE; DisableInterruptMask = 0x50; EnableInterruptMask = 0x40; TaskLevelMask = 0x40; IsrStackSize = 255; NodeNumber = 5; MaxPrio = 5; SchedStackSize = 255; NodeStackSize = 255; NodeStack = FALSE; MultiplyActivation = TRUE; }; User's Manual 284 OSEK Operating System -- Rev 1.2 System Service Timing MOTOROLA It is possible that some real numbers can slightly differ from the presented values due to some last changes in OSEK OS. Table B-1. OSEKOS_20 version of the Operating System run-time services timing characteristics (HC12D60, Cosmic software)(1) Conditions IR ST TW TWCS - - 301 - NONPREEMPT - - 546 - Initial - - 601 692 - 240 - - NONPREEMPT - 455 - - Initial - 447 - - BCC1, NONPREEMPT, STATUS=STANDARD, Counters=FALSE, Alarms=FALSE, UnqueuedMessages=FALSE, QueuedMessages=FALSE, no hook routines, no interrupts N O N - D I S C L O S U R E ActivateTask TerminateTask BCC1, NONPREEMPT, STATUS=STANDARD, Counters=FALSE, Alarms=FALSE, UnqueuedMessages=FALSE, QueuedMessages=FALSE, no hook routines, no interrupts ChainTask OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Service Timing A G R E E M E N T All numbers in the table are the number of CPU cycles counted by reading the free running counter. Therefore, to calculate these numbers in microseconds, these numbers must be multiplied by the period of CPU clock. For instance, for HC12D60 with 16Mhz oscillator, CPU clock frequency equals 8Mhz and the CPU clock period equals 0.125 microseconds the duration of GetResource service (for "Initial" system configuration) is 34.125 microseconds (273 * 0.125*10-6 = 34.125*10-6). R E Q U I R E D System Service Timing General Notes 285 Table B-1. OSEKOS_20 version of the Operating System run-time services timing characteristics (HC12D60, Cosmic software)(1) Conditions IR ST TW TWCS - - - 441 NONPREEMPT - - - 845 Initial - - - 821 67 - - 115 NONPREEMPT 123 - - 266 Initial 123 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 353 BCC1, NONPREEMPT, STATUS=STANDARD, Counters=FALSE, Alarms=FALSE, UnqueuedMessages=FALSE, QueuedMessages=FALSE, no hook routines, no interrupts Schedule BCC1, NONPREEMPT, STATUS=STANDARD, Counters=FALSE, Alarms=FALSE, UnqueuedMessages=FALSE, QueuedMessages=FALSE GetTaskId Initial 48 GetTaskState Initial: N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D System Service Timing running task ready task suspended task 68 226 266 EnterISR Resources=TRUE, FastResource=TRUE 53 LeaveISR Resources=TRUE, FastResource=TRUE 114 EnableInterrupt Resources=TRUE, FastResource=TRUE 33 DisableInterrupt Resources=TRUE, FastResource=TRUE 32 GetInterruptMask Resources=TRUE, FastResource=TRUE 26 GetResource Resources=TRUE, FastResource=TRUE 97 ReleaseResource Resources=TRUE, FastResource=TRUE 151 User's Manual 286 OSEK Operating System -- Rev 1.2 System Service Timing MOTOROLA Table B-1. OSEKOS_20 version of the Operating System run-time services timing characteristics (HC12D60, Cosmic software)(1) Conditions IR ST TW TWCS SetEvent ECC1, NONPREEMPT 102 - 144 - ECC1 102 - 180 280 ECC1, NONPREEMPT 29 - - - ECC1 29 - - - A G R E E M E N T ClearEvent GetEvent ECC1, NONPREEMPT 98 - - - ECC1 98 - - - 169 - - 187 - - - - - - - - - - - - - - - - - - 741 869 - - - - - - - 682 808 WaitEvent ECC1, NONPREEMPT 38 ECC1 38 SendMessage BCC1, an unqueued message with copy (2) 107 ReceiveMessage BCC1, an unqueued message with copy (2) 111 R E Q U I R E D System Service Timing General Notes (3) BCC1, queued message, 1 receiver 209 ReceiveMessage BCC1, queued message, 1 receiver N O N - D I S C L O S U R E SendMessage (3) 250 InitCounter Resources=TRUE, FastResource=TRUE 128 (4) CounterTrigger Resources=TRUE, FastResource=TRUE 151 GetCounterValue Resources=TRUE, FastResource=TRUE 107 GetCounterInfo Resources=TRUE, FastResource=TRUE 82 (4) SetRelAlarm Resources=TRUE, FastResource=TRUE 188 SetAbsAlarm (4) OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Service Timing 287 R E Q U I R E D System Service Timing Table B-1. OSEKOS_20 version of the Operating System run-time services timing characteristics (HC12D60, Cosmic software)(1) Conditions IR ST TW TWCS Resources=TRUE, FastResource=TRUE 220 - 714 840 - - - - - - CancelAlarm(4) Resources=TRUE, FastResource=TRUE 100 GetAlarm(4) 100 1. In all configurations number of task objects is 5. 2. In this configuration number of message objects is 7. 3. In this configuration number of message objects is 8. 4. In this configuration number of alarm objects is 1. N O N - D I S C L O S U R E A G R E E M E N T Resources=TRUE, FastResource=TRUE User's Manual 288 OSEK Operating System -- Rev 1.2 System Service Timing MOTOROLA C.2 Memory for the OSEK Operating System. . . . . . . . . . . . . . . .289 C.3 Data Sheet for the Cosmic . . . . . . . . . . . . . . . . . . . . . . . . . . .292 C.2 Memory for the OSEK Operating System The table below contains the data about ROM and RAM needed for the OSEK Operating System kernel and system objects. The amount of memory depends on the system configuration and on the number of certain objects (e.g., tasks, counters, etc.). The table does not reflects all possible configurations so the overall number of them is too big (more than 2000). Therefore, only some most important configurations are presented. The following initial system property settings were used to determine memory requirements: OSVERSION = 2; TargetMCU = HC12; HCBankCode = FALSE; HCBasePage = TRUE; HCLowPower = FALSE; CC = BCC1; EntryExitISR = FALSE; InterruptMaskControl = FALSE; SCHEDULE = FULL; SimpleScheduler = TRUE; UseMainStack = FALSE; UseSameContext = TRUE; MultiplyActivation = FALSE; TaskIndexMethod = FALSE; TaskBasePage = TRUE; NodeStack = FALSE; StackPool = FALSE; TaskOwnStack = TRUE; OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Memory Requirements 289 R E Q U I R E D C.1 Contents A G R E E M E N T Appendix C. Memory Requirements N O N - D I S C L O S U R E User's Manual -- OSEK Operating System R E Q U I R E D Memory Requirements A G R E E M E N T PersistentNode = FALSE; PersistentStack = FALSE; STATUS = STANDARD; HookRoutines = FALSE; ErrorHook = FALSE; StartupHook = TRUE; ShutdownHook = TRUE; PreTaskHook = FALSE; PostTaskHook = FALSE; InternalErrorHandler = FALSE; Resources = FALSE; FastResource = FALSE; Events = FALSE; Counters = FALSE; CounterSize = 8; Alarms = FALSE; AlarmList = FALSE; UnqueuedMessages = FALSE; UnqueuedMsgDefaultValue = FALSE; QueuedMessages = FALSE; QueuedMsgOneToN = FALSE; ActivateOnMsg = FALSE; AlarmOnMsg = FALSE; SetEventOnMsg = FALSE; N O N - D I S C L O S U R E This initial property list was used for the first row in the table. It conforms to the BCC1 Conformance Class without any additional mechanisms and this is the minimal OSEK OS configuration. The rows below reflects memory requirements for the next Conformance Classes. System properties are shown in the rows which are turned on for the corresponded Conformance Class. For BCC2, ECC1, ECC2 the scheduler policy is full-preemptive one. All other rows below the first one ("Initial") has a title "Initial" or "Changed:" and one or more options turned ON or OFF. If a row has a title "Initial" it means that for such OS configuration the Initial property list is used with particular options changed as shown. If a row has a title "Changed:" it means that for such OS configuration the setting list as for the previous row is used with particular options changed as shown. Thus, the system functionality grows up. Under the title "Extensions" the additions are shown for each additional system property (or group of them). These numbers are got on the base of ECC2 configuration. For example, the row "Counters = ON" presents the additional memory requirements for this mechanism. It allows the User's Manual 290 OSEK Operating System -- Rev 1.2 Memory Requirements MOTOROLA Since each system object (a task, a message, an alarm, etc.) requires some ROM and RAM the total amount of memory depends on the number of objects. Therefore, the formulas should be used to calculate the exact memory amount for each case. These formulas are provided in the table. In the formulas in the table the following symbols are used: * Ts is the number of tasks in non-suspended state; * Tt is the total number of tasks; * C is the number of counters; * A is the number of alarms; * S is the number of unqueued messages; * E is the number of queued messages; * P is the number of tasks' priorities; * R is the number of resources; * Sp is the number of stack pools; * Sb is the number of stack buffers. N O N - D I S C L O S U R E NOTE: It is possible that some real numbers can slightly differ from the presented values due to some last changes in OSEK OS. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Memory Requirements A G R E E M E N T user to evaluate the amount of memory needed to support some particular mechanisms and features. Differences between the amount of memory required to support these features for various Conformance Classes are comparatively small. Therefore, the data is provided only for ECC2. Thus, since each next row includes all functionality of the previous ones, the last row presents the memory requirements for the system with full functionality. R E Q U I R E D Memory Requirements Memory for the OSEK Operating System 291 C.3 Data Sheet for the Cosmic Table C-1. OSEKOS_20 version of the Operating System memory requirements RAM Base Page RAM Initial - 840+7*Tt 23+7*Ts 1 Initial SCHEDULE = NON - 825+7*Tt 23+9*Ts 2 Initial SCHEDULE = MIXED - 840+7*Tt 23+7*Ts 3 Initial SCHEDULE = MIXED UseSameContext = FALSE - 894+7*Tt 23+9*Ts 4 Changed: HCBasePage = FALSE TaskBasePage = FALSE 23+7*Ts 890+7*Tt - 5 Changed: STATUS = EXTENDED 21+7*Ts 1001+10*Tt - 6 Changed: ErrorHook = TRUE 21+7*Ts 1001+10*Tt - 7 Changed: STATUS = STANDARD ErrorHook = FALSE EntryExitISR = TRUE 25+7*Ts 1056+7*Tt - 8 Changed: InterruptMaskControl = TRUE 27+7*Ts 1165+8*Tt - 081 Changed: Reconfig = TRUE 27+7*Ts 1191+10*Tt - 9 Initial SimpleScheduler = FALSE - 936+7*Tt 29+10*Ts+4*P 10 Changed: HCBasePage = FALSE TaskBasePage = FALSE 29+10*Ts+4*P 991+7*Tt - 11 Initial SimpleScheduler = FALSE MultiplyActivation = TRUE - 1266+11*Tt 31+10*Ts+4*P System Properties (configuration) 0 N O N - D I S C L O S U R E Conformance Class ROM Number A G R E E M E N T R E Q U I R E D Memory Requirements BCC1 BCC2 12 Changed: HCBasePage = FALSE TaskBasePage = FALSE 31+10*Ts+4*P 1330+11*Tt - 13 Changed: STATUS = EXTENDED 29+10*Ts+4*P 1456+14*Tt - 14 Changed: ErrorHook = TRUE 29+10*Ts+4*P 1541+14*Tt - User's Manual 292 OSEK Operating System -- Rev 1.2 Memory Requirements MOTOROLA Conformance Class ROM RAM Base Page RAM Initial SimpleScheduler = FALSE Events = TRUE - 1075+7*Tt 29+12*Ts+4*P 16 Changed: HCBasePage = FALSE TaskBasePage = FALSE 29+12*Ts+4*P 1135+7*Tt - 17 Changed: STATUS = EXTENDED 27+12*Ts+4*P 1336+10*Tt - 18 Changed: ErrorHook = TRUE 27+12*Ts+4*P 1502+10*Tt - 19 Changed: STATUS = STANDARD ErrorHook = FALSE EntryExitISR = TRUE 31+12*Ts+4*P 1349+7*Tt - 20 Changed: InterruptMaskControl = TRUE 33+12*Ts+4*P 1494+8*Tt - 21 Initial SimpleScheduler = FALSE MultiplyActivation = TRUE Events = TRUE - 1407+11*Tt 31+12*Ts+4*P Number System Properties (configuration) 15 ECC1 N O N - D I S C L O S U R E ECC2 A G R E E M E N T Table C-1. OSEKOS_20 version of the Operating System memory requirements R E Q U I R E D Memory Requirements Data Sheet for the Cosmic OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Memory Requirements 293 Table C-1. OSEKOS_20 version of the Operating System memory requirements Number Conformance Class System Properties (configuration) ROM RAM Base Page RAM Extensions (based on the configuration for ECC2) N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Memory Requirements Changed: Resources = TRUE 2*R 23 Changed: FastResource = TRUE - 24 Changed: Counters = TRUE 1*C 1666+11*Tt+4 33+12*Ts+4*P *C 25 Changed: CounterSize = 16 2*C 1674+11*Tt+6 33+12*Ts+4*P *C 26 Changed: CounterSize = 32 4*C 1716+11*Tt+1 33+12*Ts+4*P 0*C 27 Changed: Alarms = TRUE CounterSize = 8 3*C+8*A 2108+11*Tt+6 33+12*Ts+4*P *C+7*A 28 Changed: AlarmList = TRUE 3*C+11*A 2115+11*Tt+4 33+12*Ts+4*P *C+7*A 29 Changed: UnqueuedMessages = TRUE 3*C+11*A+3* S 2445+11*Tt+4 33+12*Ts+4*P *C+7*A+5*S 30 Changed: UnqueuedMsgDefaultValue = TRUE 3*C+11*A+3* S 2478+11*Tt+4 33+12*Ts+4*P *C+7*A+7*S 31 Changed: QueuedMessages = TRUE 3*C+11*A+3* S+39*E 2711+11*Tt+4 *C+7*A+7*S+ 33+12*Ts+4*P 11*E 32 Changed: QueuedMsgOneToN = TRUE 3*C+11*A+3* S+39*E 2830+11*Tt+4 *C+7*A+7*S+ 33+12*Ts+4*P 15*E 33 Changed: ActivateOnMsg = TRUE 3*C+11*A+3* S+39*E 2891+11*Tt+4 *C+7*A+10*S 33+12*Ts+4*P +18*E 34 Changed: SetEventOnMsg = TRUE 3*C+11*A+3* S+39*E 2907+11*Tt+4 *C+7*A+10*S 33+12*Ts+4*P +18*E 35 Changed: AlarmOnMsg = TRUE 3*C+11*A+3* S+39*E 3052+11*Tt+4 *C+7*A+13*S 33+12*Ts+4*P +21*E 36 Changed: StackPool = TRUE 4*Sp+3*C+11* A+3*S+43*E 3218+11*Tt+1 0*Sp+4*C+7* 33+14*Ts+4*P A+13*S+21*E ECC2 User's Manual 294 1562+11*Tt+3 31+14*Ts+4*P *R 22 1546+11*Tt 33+12*Ts+4*P OSEK Operating System -- Rev 1.2 Memory Requirements MOTOROLA Conformance Class Base Page RAM System Properties (configuration) 37 Changed: NodeStack = TRUE 4*Sp+3*C+11* A+3*S+47*E 3265+11*Tt+1 0*Sp+4*C+7* 33+16*Ts+4*P A+13*S+21*E 38 Changed: PersistentNode = TRUE 4*Sp+3*C+11* A+3*S+47*E 3348+13*Tt+1 0*Sp+4*C+7* 33+16*Ts+4*P A+13*S+21*E 39 Changed: PersistentStack = TRUE 4*Sp+3*C+11* A+3*S+47*E 3390+13*Tt+1 0*Sp+4*C+7* 33+16*Ts+4*P A+13*S+21*E 40 Changed: HCBasePage = FALSE TaskBasePage = FALSE 33+16*Ts+4*P 3430+13*Tt+1 +4*Sp+3*C+1 0*Sp+4*C+7* 1*A+3*S+47* A+13*S+21*E E - 41 Changed: STATUS = EXTENDED 31+16*Ts+4*P 4058+16*Tt+1 +4*Sp+3*C+1 0*Sp+7*C+7* 3*A+5*S+47* A+13*S+21*E E - 42 Changed: ErrorHook = TRUE 31+16*Ts+4*P 4431+16*Tt+1 +4*Sp+3*C+1 0*Sp+7*C+7* 3*A+5*S+47* A+13*S+21*E E - 43 Changed: EntryExitISR = TRUE 33+16*Ts+4*P 5125+16*Tt+1 +4*Sp+3*C+1 0*Sp+7*C+7* 3*A+5*S+49* A+13*S+21*E E - 44 Changed: InterruptMaskControl = TRUE 35+16*Ts+4*P 5349+17*Tt+1 +4*Sp+3*C+1 0*Sp+7*C+7* 3*A+5*S+51* A+13*S+21*E E - ECC2 ROM OSEK Operating System -- Rev 1.2 MOTOROLA RAM N O N - D I S C L O S U R E Number User's Manual Memory Requirements A G R E E M E N T Table C-1. OSEKOS_20 version of the Operating System memory requirements R E Q U I R E D Memory Requirements Data Sheet for the Cosmic 295 N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Memory Requirements User's Manual 296 OSEK Operating System -- Rev 1.2 Memory Requirements MOTOROLA D.1 Contents D.2 Error Message Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .297 D.3 Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .297 D.4 Warning Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .314 D.2 Error Message Format The System Generator checks the compatibility of properties, parameters and limits and reports about possible errors via error messages. The error messages are divided into errors and warnings. By convention messages are divided into subgroups according to related objects. The error code is presented by the following string LNN##: R E Q U I R E D Appendix D. System Generation Error Messages A G R E E M E N T User's Manual -- OSEK Operating System NN presents the group number, ## presents the error number inside the group. An error message includes the file name, the line number, the error code and a short error (or warning) description. The error message has one of the following formats: <filename>(<line number>) : error ENN## : <message> <filename>(<line number>) : warning WNN## : <message> Below all System Generator error and warning messages are described. D.3 Error Messages E0001: syntax error OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Generation Error Messages 297 N O N - D I S C L O S U R E L is equal to "E" for error and" W" for warning, R E Q U I R E D System Generation Error Messages A syntax error was found in the input stream. Problems of this type can sometimes be attributed to a syntactical or clerical error. For example: TASK taskA { PRIORITY = 5 SCHEDULE = FULL; }; // No closing semicolon A G R E E M E N T In the preceding example, the error message will be generated for the line which contains the definition of SCHEDULE attribute, although the true source of the error appears on the line just above. As a general rule, make sure to also examine the lines above the line listed in the error message when trying to determine the cause. E0002: invalid token '<token>' An invalid (unrecognizable) token was found in the input stream. E0003: unexpected end of file found in comment The system generator found the end of a file while scanning a comment. A comment cannot be split across source files. N O N - D I S C L O S U R E This error can also be caused by a comment on the last line of a source file that is not followed by the `CR' symbol as in the example: int i; // error: last line not terminated by newline To eliminate this error, go to the end of the line and add a new line. E0004: Unexpected EOF The system generator reached the end of a source file without resolving a construct. For instance, a object definition may be missing a closing curly brace. E0005: End of line in STRING A string constant was continued on a second line without a backslash (\) or the closing double-quote missed. To break a string constant that is on two lines in the source file, end the first line with the line-continuation character, a backslash. User's Manual 298 OSEK Operating System -- Rev 1.2 System Generation Error Messages MOTOROLA This file either did not exist, could not be opened, or was not found. There are three possible reasons of that: - This error can occur if the file, subdirectory, or disk on which it resides is read-only. In this case, make the file writable or move the file to a writable disk. - Trying to open a file or directory for which you do not have permission can cause this error. - If an include file could not be opened, check that the INCLUDE environment variable is set correctly and that the name of the file is spelled correctly. E0012: cannot read file: <name> The system generator encountered an error when trying to read a file. This error can be caused by a disk error or by a file-sharing conflict. A G R E E M E N T E0011: cannot open source file: <name> cannot open include file: <name> cannot open output file: <name> R E Q U I R E D System Generation Error Messages Error Messages An error occurred while SG was trying to write into the file. E0014: Disk is full An error occurred while the system generator was trying to write to the output file. The cause of this error is insufficient disk space. E0015: Template file not found The system generator could not find template file for use in the generation process because the command-line option or SYSGEN_TEMPLATE environment variable was set to an invalid filename. To eliminate this error, either correct command line or use the SET command to change the SYSGEN_TEMPLATE environment variable so that it points to a valid filename. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Generation Error Messages 299 N O N - D I S C L O S U R E E0013: cannot write file: <name> R E Q U I R E D System Generation Error Messages E0020: <flag> requires an argument A command-line option requires an argument, but nothing is specified. E0021: no input file specified The input file is not specified in the command line. E0030: Incorrect object name A G R E E M E N T Incorrect name was defined for object. The first character of an identifier name must be an underscore or an uppercase or lowercase letter. The next characters of an identifier name must be an underscore or an uppercase or lowercase letter or a digit. The following OIL keywords can not be used as identifier: STRING, INT, BOOLEAN, ENUM, AUTO, WITH_AUTO, CPU, GROUP, CFG, PCFG, CONSTANT, NETWORK, OS, TASK, MESSAGE, STACK, ISR, EVENT, RESOURCE, COUNTER, ALARM, COM, NM, NODE, NETMESSAGE, CONNECTION, LINK, NMCFGALARM, NMSTATEALARM. N O N - D I S C L O S U R E E0032: Undefined object type The non-standard object type was detected, object definition ignored. E0033: This OIL version is not supported The unsupported OIL version was defined as value for the OIL_VERSION attribute. E0034: Undefined OIL version The undefined OIL version was detected. E0035: Only one CPU can be defined in the STANDARD OIL E0036: Configuration is not supported in the STANDARD OIL E0037: Object library is not supported in the STANDARD OIL E0038: CPU <name>: CFGACTIVE attribute is not supported in the Standard format User's Manual 300 OSEK Operating System -- Rev 1.2 System Generation Error Messages MOTOROLA The CFGACTIVE attribute was defined while the CFG with desired name was not detected. E0040: Same name <name> is used for different objects. CPU <cpu>: Same name for several object inside cfg: <name> CPU <cpu>: Same name for several object inside Cpu: <name> The given name has already been used for a system object of the other type. E0041: <object type> objects are not supported The object type is not supported in the current implementation. E0042: No NET can be defined in the STANDARD OIL The standard OIL format is intended to define simple application inside separate CPU without NETWORK configuration. E0043: Project Configuration is not supported in the STANDARD OIL The standard OIL format is intended to define simple application inside separate CPU without using Project configuration. E0044: Constant Table is not supported in the STANDARD OIL The standard OIL format is intended to define simple application without using Constant tables. E0046: Invalid reference The reference was not defined in the implementation. E0047: <name> reference is single, so only one parameter will be processed! The set of values was listed for single reference. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Generation Error Messages 301 A G R E E M E N T E0039: CPU <name>: Active CFG <cfg> is not defined. Attribute "CFGACTIVE" deleted N O N - D I S C L O S U R E The standard OIL format is intended to define simple application inside separate CPU without using object library and configuration. R E Q U I R E D System Generation Error Messages Error Messages R E Q U I R E D System Generation Error Messages E0048: Unresolved reference from <name> to <name> The referenced object was not found. E0049: Invalid referenced object type from <name> to <name> The referenced object type does not correspond to reference type. E0050: CPU <name>: More than one OS defined inside local object CPU <name>: More than one OS defined inside cfg: <name> A G R E E M E N T Only one OS shall be defined for application. E0051: Desired cpu <name> is not defined in the file No cpu was defined in the file Either the CPU specified in command line was not found in the file or no CPU was defined in the file. E0052: Active Project CFG <pcfg> is not defined The PCFGACTIVE attribute was defined while the PCFG with desired name was not detected. N O N - D I S C L O S U R E E0053 no <name> configuration defined inside <cpu> CPU no <name> configuration defined inside <net> NETWORK The setting for CPU or NETWORK was defined inside PCFG but the referenced CFG was not defined for defined object. E0054: unresolved reference from project configuration <pcfg> to <name> The setting for CPU or Network was defined inside PCFG but neither CPU nor NETWORK with the name was defined. E0055: redefinition of <name> table item The given identifier was defined twice inside table (either Constant or Project configuration table). The system generator used the second definition. E0056: redefinition of CPU <cpu> configuration User's Manual 302 OSEK Operating System -- Rev 1.2 System Generation Error Messages MOTOROLA More than one Implementation definition was found in the input file. E0071: Redefined type of reference does not correspond to previously defined. New type ignored! Other reference type defined for standard reference. E0072: Redefined type of referenced object does not correspond to previously defined Other referenced object type defined for standard reference. E0073: Redefined type of attribute does not correspond to standard. Definition ignored Other type of standard attribute defined. E0074: Attribute redefinition: previous attribute definition ignored Implementation specific attribute was defined twice, only last definition make a sense. E0075: Invalid default value Default value does not correspond to attribute type or attribute value range. E0076: Range value does not correspond to attribute type, ignored Range value does not correspond to attribute type. E0077: undefined type of referenced object The undefined type of referenced object was defined in reference definition. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Generation Error Messages 303 A G R E E M E N T E0070: Only one implementation definition is allowed N O N - D I S C L O S U R E The configuration for given CPU was defined twice inside Project configuration table. The system generator used the second definition. R E Q U I R E D System Generation Error Messages Error Messages R E Q U I R E D System Generation Error Messages E0080: <attribute name> attribute is not defined in the implementation The used implementation does not correspond to current version of system generator. Check your implementation file or contact vendor. E0090: the <name> application mode is not defined A G R E E M E N T The application mode is listed as the CFG_ACTIVE attribute value but there is not the CFG with defined name. E0091: only TASK can be redefined for mode Other than TASK object is defined inside CFG declared as application mode. There is restriction that only set of tasks can be varied in application mode. E0092: TargetMCU shall be defined The default value for TargetMCU is not allowed. E0100: No OS defined for Cpu: <cpu name> No OS defined inside cfg: <cfg name> N O N - D I S C L O S U R E OS is mandatory object for CPU. The OS shall be defined either in local CPU object or for each configuration. E0102: Undefined attribute The attribute was not defined in the implementation. E0103: Invalid attribute value The attribute value does not correspond to the type or range. E0104: incorrect property <name> setting The setting of the property <name> is incompatible with other current settings. E0105: method of task stack assignment is not defined At least one of task stack assignment methods shall be defined, either NodeStack or StackPool or TaskOwnStack. User's Manual 304 OSEK Operating System -- Rev 1.2 System Generation Error Messages MOTOROLA E0107: Conformance class shall be defined The CC attribute was not defined. E0108: status shall be defined The STATUS attribute was not defined. E0110: interrupt masks shall be defined The InterruptMaskControl property is turned on, but the interrupt masks are not defined. E0111: interrupt stack shall be defined The EntryExitISR property is turned on, but the interrupt stack is not defined. E0112: Multiple activation is not supported in BCC1 Multiple activation is not supported in ECC1 According to OSEK OS spec. v2.0 Multiple task activation is not supported for the BCC1 and ECC1 conformance classes. E0113: no task with multiple activation defined The MultiplyActivation property is turned on, but no task with multiple activation defined. To avoid this error turn the MultiplyActivation property of or define ACTIVATION attribute for task greater than 1. E0115: TimeModuloValue shall be defined The TimerModulo property is turned on, but TimerModuloValue is not defined. E0116: PrescalerValue shall be defined The Prescaler property is turned on, but PrescalerValue is not defined. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Generation Error Messages 305 A G R E E M E N T If SimpleScheduler is used then the resources can not be used. N O N - D I S C L O S U R E E0106: SimpleScheduler property can not be used with Resources property R E Q U I R E D System Generation Error Messages Error Messages R E Q U I R E D System Generation Error Messages E0117: resource access checking is not supported in standard status The ResourceAccessCheck property is turned on, but STANDARD status of the system defined. To avoid this error set EXTENDED status or turn ResourceAccessCheck property off. E0118: resource access checking is not supported for FastResource A G R E E M E N T The ResourceAccessCheck property is turned on, but FastResource property is turned on too. To avoid this error set FastResource property off. E0119: resource access checking is not supported for more than 8 resources The ResourceAccessCheck property is turned on, but more than 8 resources are defined. To avoid this error set ResourceAccessCheck property off. E0120: error hook shall be defined N O N - D I S C L O S U R E The ErrorHook property is turned on, but the error hook is not defined. E0121: context switch routines shall be defined The PreTaskHook or PostTaskHook property is turned on, but the corresponding routine is not defined. E0122: more than one hook of the type defined The several hooks with the same type were defined. E0123: startup hook shall be defined The StartupHook property is turned on, but the startup hook is not defined. E0124: shutdown hook shall be defined The ShutdownHook property is turned on, but the shutdown hook is not defined. User's Manual 306 OSEK Operating System -- Rev 1.2 System Generation Error Messages MOTOROLA More than one application modes are defined but Reconfig property is turned off. Either turn Reconfig property on or change definition of application mode set. E0201: the number of task control blocks shall be greater than 0 The NodeNumber attribute is equal to 0. E0202: number of priorities shall be greater than 0 The MaxPrio attribute is equal to 0. E0203: size of scheduler stack shall be defined The UseMainStack property is turned off, but the SchedulerStackSize attribute is not defined. E0204: size of task node stack shall be defined The NodeStack property is turned on, but the TaskNodeStackSize attribute is not defined. A G R E E M E N T E0160: Reconfig property turned off, no application mode supported R E Q U I R E D System Generation Error Messages Error Messages The number of task control blocks are less than maximum of task priority, it is not enough in case of SimpleScheduler. E0302: EXTENDED task not supported in BASIC classes The OS Conformance Class is defined as one of the BCC classes, but a task has the EXTENDED type. E0304: task priority exceeds the maximum limit The defined task priority is greater than MaxPrio attribute defined for OS. E0305: the number of task nodes is not enough to allocate persistent nodes The number of tasks with persistent node are greater than the number of nodes. Also this error is caused when the number of tasks with OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Generation Error Messages 307 N O N - D I S C L O S U R E E0205: number of task control blocks less than priority range R E Q U I R E D System Generation Error Messages persistent node is equal to number of nodes and there are at least one more tasks. E0306: the stack pool parameter shall be defined A task has the defined POOLSTACK stack attachment method, but the StackPool reference has not been defined. E0308: the basic task cannot be notified by event setting A G R E E M E N T The basic task is referenced by ALARM or MESSAGE to be notified by event setting. E0309: at least one task shall be defined At least one task shall be defined in the system. E0310: NodeStack property is turned off, stack cannot be allocated A task has the defined NODESTACK stack attachment method, but the NodeStack property is turned off. E0310: StackPool property is turned off, stack cannot be allocated N O N - D I S C L O S U R E A task has the defined POOLSTACK stack attachment method, but the StackPool property is turned off. E0311: task has no stack The method of task stack attachment is not defined or not supported by the OS. E0312: the stack size parameter shall be defined A task has the defined OWNSTACK attachment method, but the STACKSIZE attribute has not been defined. E0313: Multiple activation is not supported for EXTENDED task Multiple activation is not supported in BCC1 Multiple activation is not supported in ECC1 The ACTIVATION attribute has the value greater than 1, but according to OSEK OS spec. 2.0 multiple task activation is not supported in the User's Manual 308 OSEK Operating System -- Rev 1.2 System Generation Error Messages MOTOROLA The defined task preemptive property is incompatible with defined scheduling policy. E0318: task scheduling type shall be defined Task preemptive property is not defined. The SCHEDULE attribute is obligatory for TASK object. E0319: task type shall be defined The task type is not defined. The TYPE attribute is obligatory for TASK object. E0320: task priority shall be defined Task priority property is not defined. The PRIORITY attribute is obligatory for TASK object. E0321: number of task activations shall be defined Number of task activations is not defined. The ACTIVATION attribute is obligatory for TASK object. E0322: AUTOSTART task property shall be defined Initial task state is not defined. The AUTOSTART attribute is obligatory for TASK object. E0323: only EXTENDED task can have Events The BASIC task has the reference to EVENT. E0324: EVENT not supported in BASIC classes The task has the reference to EVENT. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Generation Error Messages 309 A G R E E M E N T E0314: non-preemptive tasks are not supported by full-preemptive scheduler preemptive tasks are not supported by non-preemptive scheduler N O N - D I S C L O S U R E BCC1 and ECC1 conformance classes for BACIS task and never supported for EXTENDED task. R E Q U I R E D System Generation Error Messages Error Messages R E Q U I R E D System Generation Error Messages E0325: TaskOwnStack property is turned off, stack cannot be allocated A task has the defined OWNSTACK stack attachment method, but the TaskOwnStack property is turned off. E0326: the same priority can't be defined for tasks in case of SimpleScheduler A G R E E M E N T The simplified scheduler can be used only if each task in the application has an unique priority. E0351: Size of buffer in the pool shall be defined Size of buffer in the pool shall be defined for the STACK object. E0352: Number of buffers in the pool shall be defined Number of buffers in the pool shall be defined for the STACK object. E0401: resource priority exceeds the maximum limit The defined PRIORITY attribute for RESOURCE is greater than MaxPrio attribute of OS. N O N - D I S C L O S U R E E0450: ISR category shall be defined The CATEGORY attribute is obligatory for ISR object. E0470: No tasks referencing event, AUTO mask can not be calculated If an event has AUTO as mask, then some task should have reference to this event. E0451: ISR of category 3 is not supported without EntryExitISR The ISR of category 3 has the ISR-frame which is started with EnterISR and finished by ExitISR call. The pair of function is obligatory for ISR of category 3. E0471: Events not supported in BASIC classes User's Manual 310 OSEK Operating System -- Rev 1.2 System Generation Error Messages MOTOROLA The MASK attribute is obligatory for EVENT object. E0501: system timer is already defined Only one of the defined counters shall have the SystemTimer attribute TRUE. E0502: System timer is undefined If the OS attribute SysTimer is set to TRUE but there is no COUNTER defined then the System Timer is considered as undefined. E0503: TICKDURATION attribute shall be defined for system timer The TICKDURATION attribute is not defined for system timer. The value of this attribute is used for definition of the OSTICKDURATION constant. E0511: MAXALLOWEDVALUE attribute shall be defined The MAXALLOWEDVALUE attribute is obligatory for COUNTER object. E0512: TICKSPERBASE attribute shall be defined The TICKSPERBASE attribute is obligatory for COUNTER object. E0601: assigned counter is undefined The COUNTER reference is not defined. E0602: task to event setting shall be defined The TASK reference is not defined. E0603: type of notification shall be defined The ACTION attribute is obligatory for ALARM object. E0604: task activation method is defined, event shall not be defined The task activation method is defined, but reference to event is defined too. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Generation Error Messages 311 A G R E E M E N T E0472: MASK attribute shall be defined N O N - D I S C L O S U R E The EVENT object is defined, but one of the BASIC conformance classes is defined for OS. R E Q U I R E D System Generation Error Messages Error Messages R E Q U I R E D System Generation Error Messages E0605: event to be set shall be defined The event setting task notification method is defined but reference to event is not defined. E0606: task to be notified shall be defined The TASK reference is not defined. A G R E E M E N T The ALARM has the reference to EVENT while one of the BASIC conformance classes has been defined for OS. N O N - D I S C L O S U R E E0607: Events not supported in BASIC classes The TYPE attribute is obligatory for MESSAGE object. E0608: Events property is turned off, notification can not be defined This error message is generated in the case when the SETEVENT notification action is defined but OS Events property is set to FALSE. E0706 : Queued message can not be used in without copy mode The WithCopy attribute shall be TRUE for the Queued message. E0711: message type shall be defined E0712: number of items shall be defined The ITEMS attribute is obligatory for MESSAGE object. E0713: type of item shall be defined The ITEMTYPE attribute is obligatory for MESSAGE object. E0714: reference to alarm shall be defined The ALARMRESETTIME attribute is defined but the ALARMRESET reference is not defined. E0715: alarm period shall be defined The ALARMRESET reference is defined but the ALARMRESETTIME attribute is not defined. User's Manual 312 OSEK Operating System -- Rev 1.2 System Generation Error Messages MOTOROLA E0716: task to event setting shall be defined The event setting notification method is defined but the TASK reference is not defined. E0717: Events not supported in BASIC classes The EVENT reference is defined for message while one of the BASIC conformance classes has been defined for OS. R E Q U I R E D System Generation Error Messages Error Messages The ITEMS attribute has value greater than 1 for unqueued message. E0719: type of notification shall be defined The ACTION attribute is obligatory for MESSAGE object. E0720: task activation method is defined, event shall not be defined The task activation method is defined, but reference to event is defined too. E0721: task notification method is NONE, event shall not be defined A G R E E M E N T E0718: Unqueued message can not have more than 1 items E0722: task notification method is NONE, task shall not be defined The task notification method is NONE, but reference to task is defined. E0723: task to be notified shall be defined The TASK reference is not defined. E0724: event to be set shall be defined The event setting task notification method is defined but reference to event is not defined. E0850: <filename> or "filename" expected The incorrect syntax of include directive. E0851: <filename without path> expected OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Generation Error Messages 313 N O N - D I S C L O S U R E The task notification method is NONE, but reference to event is defined. The incorrect syntax of include directive. E0852: unknown directive: <directive> Unknown preprocessing directive was detected. E0853: undefined directive No preprocessing directive was detected. D.4 Warning Messages W0020: ignoring unknown option <flag> The <flag> in the command-line option is not valid; the option is ignored. W0031: <name> : identifier was truncated to 32 characters The identifier is longer than 32 characters. W0101: <name> attribute already defined The attribute <name> has been previously defined and will be redefined. W0102: <name> reference already defined N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D System Generation Error Messages The reference <name> has been previously defined and will be redefined. W0110: UseMainStack property is turned on, parameter ignored The UseMainStack property is turned on, but either the scheduler stack or the interrupt stack is defined. W0120: ErrorHook property turned off, definition ignored The ErrorHook property is turned off, but the error hook is defined. W0121: PreTaskHook property turned off, definition ignored PostTaskHook property turned off, definition ignored The PreTaskHook or PostTaskHook property is turned off, but the corresponding routine is defined. User's Manual 314 OSEK Operating System -- Rev 1.2 System Generation Error Messages MOTOROLA W0123: ShutdownHook property turned off, definition ignored The ShutdownHook property is turned off, but the shutdown hook is defined. W0150: NetworkCOM property turned on, but this version does not support COM generation, definition ignored The NetworkCOM property is turned on, but this version of system generator does not support generation of COM objects. W0201: NodeStack property is turned off, parameter ignored If the NodeStack property is turned off then the node stacks are not supported and parameters defining this stack are ignored. W0202: there are unused task control blocks The number of task control blocks are greater than maximum defined priority of a task, therefore in case of SimpleScheduler the unused control blocks exist. W0304: Multiple activation is not supported The MultiplyActivation property is set to FALSE but the task has ACTIVATION greater than 1. W0306: PersistentNode property is turned off, parameter ignored A task has the defined PersistentNode attribute, but the OS PersistentNode property is turned off. W0307: PersistentStack property is turned off, parameter ignored A task has the defined PersistentStack attribute, but the OS PersistentStack property is turned off. W0308: persistent stack may be assigned only for task with persistent node, parameter ignored OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Generation Error Messages 315 A G R E E M E N T The StartupHook property is turned off, but the startup hook is defined. N O N - D I S C L O S U R E W0122: StartupHook property turned off, definition ignored R E Q U I R E D System Generation Error Messages Warning Messages R E Q U I R E D System Generation Error Messages A task has the defined PersistentStack attribute, but the PersistentNode attribute is not defined. The PersistentStack attribute is ignored in this case. W0309: persistent stack shall be assigned from stack pool, parameter ignored A G R E E M E N T A task has the defined PersistentStack attribute, but other than POOLSTACK stack method is defined. The PersistentStack attribute is ignored in this case. W0311: the stack address shall be defined for OWNSTACK, parameter ignored A task has the defined StackAddress attribute, but StackMethod attribute is not OWNSTACK. W0350: StackPool property turned off, definition ignored The STACK object is defined, but the StackPool property turned off. W0400: Resources property turned off, definition ignored N O N - D I S C L O S U R E The RESOURCE object is defined, but the Resources property of OS turned off. W0401: Scheduler resource has highest priority, definition ignored It is not possible to define PRIORITY for RES_SCHEDULER object. W0402: no task referencing resource Resource is defined, but not referenced by any task. W0470: Events property turned off, definition ignored The EVENT object is defined, but the Events property of OS turned off. W0500: Counters property turned off, definition ignored The Counters property of OS is turned off but the COUNTER object is defined. User's Manual 316 OSEK Operating System -- Rev 1.2 System Generation Error Messages MOTOROLA W0600: Alarms property turned off, definition ignored The Alarms property of OS is turned off but the ALARM object is defined. W0700: UnqueuedMessages property is turned off, definition ignored QueuedMessages property is turned off, definition ignored The message object is defined but corresponding OS property is turned off. W0701: UnqueuedMsgDefaultValue property is turned off, parameter ignored The DefaultValue attribute for Unqueued Message is defined, but UnqueuedMsgDefaultValue property is turned off. W0704: QueuedMsgOneToN property is turned off, parameter ignored The number of receivers is greater than one, but QueuedMsgOneToN is turned off. W0705: AlarmOnMsg property is turned off, definition ignored The ALARMRESET reference is defined, but AlarmOnMsg property is turned off. W0708: ActivateOnMsg property is turned off, definition ignored The TASK reference is defined, while the ActivateOnMsg property is turned off. W0709: SetEventOnMsg property is turned off, definition ignored The TASK and EVENT references are defined, while the SetEventOnMsg property is turned off. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual System Generation Error Messages 317 A G R E E M E N T If the counter is not the system timer then the definition of the TICKDURATION is ignored. N O N - D I S C L O S U R E W0503: TICKDURATION attribute is applied for system timer only, parameter ignored R E Q U I R E D System Generation Error Messages Warning Messages R E Q U I R E D System Generation Error Messages W0710: Queued Message cannot have default value, parameter ignored The DefaultValue attribute is defined for queued message. W0711: Number of receivers doesn't matter for Unqueued message, parameter ignored A G R E E M E N T The ReceiverNum attribute is defined for state message and has value greater than 1. W0719: Events property is turned off, parameters ignored The specified method of task notification is not supported. W1001: NETWORK objects are not supported by this version, definition ignored N O N - D I S C L O S U R E The NETWORK object is defined, but this version of system generator does not support generation of COM objects. User's Manual 318 OSEK Operating System -- Rev 1.2 System Generation Error Messages MOTOROLA E.1 Contents E.2 System Services Quick Reference . . . . . . . . . . . . . . . . . . . . .319 E.3 OIL language Quick Reference . . . . . . . . . . . . . . . . . . . . . . .325 E.2 System Services Quick Reference The brief list of all OSEK Operating System run-time services is provided below. Input and output parameters, syntax and ability to use in ISR are shown. Table E-1. OSEK OS services Service Input Output ISR Task management services Task name - Yes N O N - D I S C L O S U R E ActivateTask syntax: StatusType ActivateTask(TaskType <TaskName>); - - No - No TerminateTask syntax: StatusType TerminateTask(void); Task name ChainTask syntax: StatusType ChainTask(TaskType <TaskName>); - - No Task name No Schedule syntax: StatusType Schedule(void); - GetTaskId syntax: StatusType GetTaskId(TaskRefType <TaskName>); Task name GetTaskState GetTCBInfo1 Task state Yes syntax: StatusType GetTaskState(TaskType <TaskName>, TaskStateRefType <State>); - Task Control Block Yes syntax: StatusType GetTCBInfo(TaskControlBlockRefType <Tcb>); Interrupt management services OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Quick Reference R E Q U I R E D Appendix E. Quick Reference A G R E E M E N T User's Manual -- OSEK Operating System 319 R E Q U I R E D Quick Reference Table E-1. OSEK OS services Service Input - Output ISR - Yes - Yes - Yes EnterISR syntax: StatusType EnterISR(void); - LeaveISR syntax: StatusType LeaveISR(void); Interrupt descriptor EnableInterrupt A G R E E M E N T syntax: StatusType EnableInterrupt(IntDescriptorType <Descr>); Interrupt descriptor Yes syntax: StatusType DisableInterrupt(IntDescriptorType <Descr>); - Interrupt descriptor Yes GetInterruptDescriptor syntax: StatusType GetInterruptDescriptor(IntDescriptorRefType <Descr>); Resource management services Resource name - No GetResource syntax: StatusType GetResource(ResourceType <ResName>); Resource name - No ReleaseResource syntax: StatusType ReleaseResource(ResourceType <ResName>); Event control services Task name, Event mask SetEvent N O N - D I S C L O S U R E - DisableInterrupt - Yes syntax: StatusType SetEvent (TaskType <TaskName>, EventMaskType <Mask>); Event mask - No ClearEvent syntax: StatusType ClearEvent(EventMaskType <Mask>); Task name GetEvent Event mask Yes syntax: StatusType GetEvent(TaskType <TaskName>, EventMaskRefType <Mask>); Event mask - No WaitEvent syntax: StatusType WaitEvent(EventMaskType <Mask>); Message management services Message name, message data SendMessage syntax: StatusType SendMessage( SymbolicName <Message>, AccessName <Data>); Message name ReceiveMessage Yes2 - Message data Yes/No3 syntax: StatusType ReceiveMessage(SymbolicName <Message>, AccessName <Data>); Message name - No GetMessageResource syntax: StatusType GetMessageResource(<MessageName>); User's Manual 320 OSEK Operating System -- Rev 1.2 Quick Reference MOTOROLA Table E-1. OSEK OS services Service Input Message name Output ISR - No ReleaseMessageResource syntax: StatusType ReleaseMessageResource(<MessageName>); Message name - Yes GetMessageStatus syntax: StatusType GetMessageStatus(<MessageName>); Counter management services Counter name, initial value - No syntax: StatusType InitCounter(CtrRefType <CtrName>, TickType <Ticks>); Counter name - A G R E E M E N T InitCounter Yes CounterTrigger syntax: StatusType CounterTrigger(CtrRefType <CtrName>); Counter name, number of ticks AdvanceCounter4 Counter value No syntax: StatusType GetCounterValue(CtrRefType <CtrName>, TickRefType <Ticks>); Counter name GetCounterInfo No syntax: StatusType AdvanceCounter(CtrRefType <CtrName>, TickType <Ticks>); Counter name GetCounterValue - Counter constants R E Q U I R E D Quick Reference System Services Quick Reference No syntax: StatusType GetCounterInfo(CtrRefType <CtrName>, CtrInfoRefType <Info>); Alarm management services GetAlarmBase Alarm constants Yes N O N - D I S C L O S U R E Alarm name syntax: StatusType GetAlarmBase(AlarmType <AlarmName>, AlarmBaseRefType <Info>); Alarm name, Counter relative value, Cycle value - Yes SetRelAlarm syntax: StatusType SetRelAlarm (AlarmType <AlarmName>, TickType <Increment>, TickType <Cycle>); Alarm name, Counter absolute value, Cycle value - Yes SetAbsAlarm syntax: StatusType SetAbsAlarm (AlarmType <AlarmName>, TickType <Start>, TickType <Cycle>); Alarm name - Yes CancelAlarm syntax: StatusType CancelAlarm(AlarmType <AlarmName>); Relative value in ticks before the alarm expires Alarm name Yes GetAlarm syntax: StatusType GetAlarm(AlarmType <AlarmName>, TickRefType <Ticks>); OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Quick Reference 321 R E Q U I R E D Quick Reference Table E-1. OSEK OS services Service Input Output ISR Execution control services - Current application mode Yes GetActiveApplicationMode syntax: AppModeType GetActiveApplicationMode(void); Operating mode - No - No StartOS syntax: void startOS(ModeType <Mode>); Error code A G R E E M E N T ShutdownOS syntax: void shutdownOS(StatusType <Error>); Hook Routines Error code - Yes ErrorHook syntax: void ErrorHook(StatusType <Error>); - - Yes - Yes - No - No - No PreTaskHook syntax: void PreTaskHook(void ); - PostTaskHook syntax: void PostTaskHook(void ); - IdleLoopHook syntax: void IdleLoopHook(void ); - StartupHook N O N - D I S C L O S U R E syntax: void StartupHook(void ); - ShutdownHook syntax: void ShutdownHook(void ); 1. This service is not defined in the OSEK OS v.2.0 rev. 1 specification. This is an extension of OSEK OS. 2. Yes - for unqueued messages in WithCopy configuration only. 3. Yes - for unqueued messages in WithCopy configuration only, No - for queued messages. 4. This service is not defined in the OSEK OS v.2.0 rev. 1 specification. This is an extension of OSEK OS. The list of OSEK Operating System Data Types is provided here. Table E-2. Data Types Data Type Description StatusType The data type for all status information the API services offer (see return values for OSEK OS services in Table E-4) TaskType The abstract data type for task identification TaskRefType The data type to refer variables of the TaskType data type User's Manual 322 OSEK Operating System -- Rev 1.2 Quick Reference MOTOROLA Data Type Description TaskStateType The data type for variables to store the state of a task TaskStateRefType The data type to refer variables of the TaskStateType data type TaskControlBlockType The data type for task control block (task node) TaskControlBlockRefType The data type to refer variables of the TaskControlBlockType data type IntDescriptorType The data type for logical interrupt descriptors IntDescriptorRefType The date type to refer variables of the IntDescriptorType data type ResourceType The abstract data type for referencing a resource EventMaskType The data type of the event mask EventMaskRefType The data type to refer to an event mask CtrRefType The data type references a counter TickType The data type represents a counter value in system ticks TickRefType The data type references data corresponding to the data type TickType CtrInfoType The data type represents a structure for storage of counter characteristics. This structure has the following fields: maxallowedvalue maximum possible allowed count value; ticksperbase number of ticks required to reach a counter-specific significant unit; mincycle minimum allowed number of ticks for a cyclic alarm (only for system with Extended Status); CtrInfoRefType The data type references data corresponding to the data type CtrInfoType AlarmBaseType The data type represents a structure for storage of alarm characteristics. It is the same as CtrInfoType AlarmBaseRefType The data type references data corresponding to the data type AlarmBaseType AlarmType The data type represents an alarm element AppModeType This data type represents the operating mode SymbolicName An unique name representing a message AccessName An unique name defining access to a message object The brief list of OSEK Operating System Constructional elements is provided below. Table E-3. Constructional elements Name DeclareTask Description Serves as an external declaration of a task. The function and use of this service are similar to that of the external declaration of variables syntax: DeclareTask(TaskType <TaskId>) OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Quick Reference 323 N O N - D I S C L O S U R E Table E-2. Data Types A G R E E M E N T R E Q U I R E D Quick Reference System Services Quick Reference R E Q U I R E D Quick Reference Table E-3. Constructional elements Name DeclareEvent Description Serves as an external declaration of an event. The function and use of this service are similar to that of the external declaration of variables syntax: DeclareEvent(EventMaskType <Event>) DeclareResource Serves as an external declaration of a resource. The function and use of this service are similar to that of the external declaration of variables syntax: DeclareResource(ResourceType <ResId>) Serves as an external declaration of an alarm element A G R E E M E N T DeclareAlarm syntax: DeclareAlarm(AlarmType <AlarmId>) Serves as an external declaration of a counter DeclareCounter syntax: DeclareCounter(CtrRefType <CounterId>) DeclareISR Serves as an external declaration of an ISR. The function and use of this service are similar to that of the external declaration of variables. This service is not defined in OSEK OS v.2.0 specification. This is an extension of OSEK OS. syntax: DeclareISR(<ISRName>) The table below contains all return values for OSEK Operating System run-time services and error values. Table E-4. OSEK Operating System run-time services return values and error values N O N - D I S C L O S U R E Name Value Type E_OK 0 No error, successful completion E_OS_ACCESS 1 Access to the service/object denied E_OS_CALLEVEL 2 Access to the service from the ISR is not permitted E_OS_ID 3 The object ID is invalid E_OS_LIMIT 4 The limit of services/objects exceeded E_OS_NOFUNC 5 The object is not used, the service is rejected E_OS_RESOURCE 6 The task still occupies the resource E_OS_STATE 7 The state of the object is not correct for the required service E_OS_VALUE 8 A value outside of the admissible limit E_OS_SYS_STACK 10 Internal stack overflow E_COM_BUSY 1 Message in use by application task/function E_COM_ID 3 Invalid message name passed as parameter E_COM_LIMIT 4 Overflow of FIFO associated with queued messages E_COM_LOCKED 7 Rejected service call, message object locked due to a pending operation E_COM_NOMSG 9 No message available User's Manual 324 OSEK Operating System -- Rev 1.2 Quick Reference MOTOROLA Constant Value Description RUNNING 0 Constant of data type TaskStateType for task state running WAITING 1 Constant of data type TaskStateType for task state waiting READY 2 Constant of data type TaskStateType for task state ready SUSPENDED 3 Constant of data type TaskStateType for task state suspended INVALID_TASK (TaskType)-1 Constant of data type TaskType for a not defined task RES_SCHEDULER (ResourceType)0 If Resource = FALSE or FastResource = FALSE in configuration OIL-file (ResourceType)-1 If Resource = TRUE and FastResource = TRUE in configuration OIL-file Constant of data type ResourceType for Scheduler as a resource OSMAXALLOWEDVALUE Maximum possible allowed count value OSTICKPERTIME OSTICKSPERBASE Number of ticks that are required to reach 10 milliseconds in the system timer OSTICKDURATION Depends on user's settings in configuration OIL-file Number of ticks required to reach a counter-specific significant unit OSMINCYCLE Minimum allowed number of ticks for a cyclic alarm (only for system with Extended Status) INITIAL_INTERRUPT_ DESCRIPTOR Initial interrupt level during system startup E.3 OIL language Quick Reference The lists of the all OIL object parameters with their possible values and short descriptions are provided here. All standard object attributes must be always defined. Motorola's specific attributes can be defined in addition to standard ones. The value used by default typed by the boldface type in the Possible Values cells. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Quick Reference 325 A G R E E M E N T Table E-5. OSEK Operating System constants N O N - D I S C L O S U R E The following table contains OSEK Operating System constants with short description. R E Q U I R E D Quick Reference OIL language Quick Reference R E Q U I R E D Quick Reference E.3.1 OS Object The OS object is the mandatory one for any application. It defines OS and its properties for the application. The OS object has the standard and Motorola's specific attributes. These attributes exactly corresponds to the system options and are divided into parts which correspond to appropriate system objects. Table E-6. OS Parameters A G R E E M E N T Object Parameters Description Notes Standard Attributes CC SCHEDULE N O N - D I S C L O S U R E Possible Values STATUS BCC1, BCC2, ECC1, ECC2, AUTO OSEK Conformance Class. Defines general OS functionality and OS behavior. However, most features of the OS may be selected by means of using other OS additional properties. Therefore, even for given conformance class the functionality may be reduced or increased according to user's needs. BCC3 Conformance Class is also supported in Motorola OS v.1.0. NON, FULL, MIXED, AUTO Scheduling Policy. Determines whether OS supports non-preemptive task only, preemptive task only, or both. The preemptive scheduling allows better timing for external events, while it adds overhead for more often context switching. For application with all short tasks non-preemptive scheduling policy is recommended. It is recommended do not use mixed scheduling policy unless absolutely necessary, because it increases code size and timing. In general, the task context differs for preemptive and nonpreemptive tasks. Preemptive task context requires more stack space. Defines whether additional run-time error checks are supported by OS for OSEK API calls or not. The extended status adds approximately 10% of code, and increases timing accordingly. As a general approach, it is recommended to start application development with extended status to discover configuration and run-time problems. For debugged applications the status may be set to standard to reduce code size and advance timing. STANDARD, EXTENDED User's Manual 326 OSEK Operating System -- Rev 1.2 Quick Reference MOTOROLA StartupHook ShutdownHook PreTaskHook PostTaskHook Possible Values Description Notes TRUE, FALSE Defines that user's-provided hook is called after the operating system startup and before the scheduler is running. This hook may be used by the application to perform hardware initialization actions, task activations, alarm setting, etc. The alternative way is to make such initialization steps in the task, which starts automatically. The hook is called with disabled interrupts. Particular main() function should not be used for OS-dependent initialization actions like task activation, alarm setting, because at this time OS is not running. TRUE, FALSE Defines that user's-provided hook is called when the OS shutdown service is performed. The main purpose of this hook is to shutdown initialized hardware devices like timers, network controllers, etc. Besides, the reason for shutdown may be obtained through the error code. This hook is called before system timer shutdown (if system timer is configured in the system). The status of interrupts is undefined, so it should be controlled by the user. TRUE, FALSE Defines that user's-provided hook is called from the scheduler code before the operating system enters context of the task. In general, this hook is designed for debugging applications by means of tracing current task. This hook is called within the task or interrupt service routine. It is not recommended to use this hook in normal working applications, because it adds significant timing overhead. If defined, this hook is called for each task, i.e. it is not allowed to use this hook for particular task(s) only. TRUE, FALSE Defines that user's-provided hook is called from the scheduler code after the operating system leaves context of the task. In general, this hook is designed for debugging applications by means of tracing current task. This hook is called within the task or interrupt service routine. It is not recommended to use this hook in normal working applications, because it adds significant timing overhead. If defined, this hook is called for each task, i.e. it is not allowed to use this hook for particular task(s) only. OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Quick Reference 327 A G R E E M E N T Object Parameters N O N - D I S C L O S U R E Table E-6. OS Parameters R E Q U I R E D Quick Reference OIL language Quick Reference N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Quick Reference Table E-6. OS Parameters Object Parameters ErrorHook Possible Values TRUE, FALSE Description Notes Defines that user's-provided hook is called by the Operating System at the end of each system service which returns a value not equal to E_OK. This hook is designed for debugging applications by means of tracing error code, returned by the system service instead of checking error code after each call of system service. This hook increases the OS code with extended error status by approximately 11%, and increase the timing in case of error during the service call. There is no need to check the error status of the each OS service call if this hook is used. However, the mean of identifying source of error should be implemented somehow in the application. This hook is useful as a temporary feature of a working (debugged) applications when some troubles occur. If defined, this hook is called for each system service, i.e. it is not allowed to use this hook for particular service(s) only. Motorola's Specific Attributes Global System Attributes This group of OS attributes represents system features which are common for the whole system OSVERSION 1, 2 OSEK OS version used. In general, version 1.0 is supported for backward compatibility only, and the support will be dropped from future releases of the product. However, the implementation support services, which are defined in OSEK OS Specifications v1.0, but which are removed from OSEK OS Specifications v2.0. For example, counters and message services may still be used. OS v.2.0 used by default. If the portability of the application is an issue, then it is recommended to avoid usage of system services, which are not defined in official OSEK OS Specifications. To build application for OSEK OS v1.0 Specs. this attribute should be set equal 1. HC08, HC12, CPU32, WINNT, MPC, MCORE Target MCU type. This attribute defines the core, for which the OS will be configured. In addition, if a number of microcontroller families is supported by the OS, then the particular family will be defined during compilation/linking time by means of defining special identifier for the family (for example, OSHC12A4 should be defined in the compiler command line if HC12A4 family is a target). Usually only one target may be used in the supplied code, but this attribute should be defined anyway, because some additional checks are performed for each particular target. It is highly recommended to use sample makefile as a basis for building application to provide consistency in compiler/linker settings. 0, 1 Specifies the ORTI support in OS. The attribute can have values 0 or 1. If the system has the DEBUG_LEVEL = 0 the static ORTI support is switched off. If the system has the DEBUG_LEVEL = 1 this mode is considered to be a debugging mode. This attribute is only valid for OSEK OS supporting ORTI (see Section 18 ORTI Implementation for the details). TargetMCU DEBUG_LEVEL User's Manual 328 OSEK Operating System -- Rev 1.2 Quick Reference MOTOROLA ORTIRunningTask ORTICurrentService NetworkCOM HCBasePage HCBankCode Possible Values Description Notes TRUE, FALSE Specifies that the running task identification in run-time support will be used. This attribute will be ignored if DEBUG_LEVEL = 0. This attribute is only valid for OSEK OS supporting ORTI (see Section 18 ORTI Implementation for the details). TRUE, FALSE Specifies that the OSEK OS system calls identification in run-time support will be used. This attribute will be ignored if DEBUG_LEVEL = 0. This attribute is only valid for OSEK OS supporting ORTI (see Section 18 ORTI Implementation for the details). Defines whether the COM support is provided by OS or not. If there is no network, then this attribute should be defined as FALSE to avoid overhead, connected with communication code. FALSE by default. TRUE, FALSE Defines that OS system variables will be allocated in the base page or in non-volatile registers. Depending on the OS configuration, the system variables consume from several bytes to several dozens of bytes in base page. The code size is decreased by approximately 5%, and timing is improved accordingly, because addressing to base page usually takes less space and processor cycles. Supported for HC08, HC12 for base page (address range 00 16FF16), and for MPC (few general registers are used to hold often used OS variables). It is recommended to use base page for OS system variables, if there is enough space in it. In this case, application should be linked correctly to provide proper allocation of data in base page. It is highly recommended to use sample makefile as a basis for using this attribute properly (in compiler/linker settings). However, some MCUs use base page for input-output registers, which prevents the using of it for variables. TRUE, FALSE Defines that the support of Bank Switching is used in the OSEK OS. The microcontroller memory bank hardware should be supported by the compiler. This is useful when memory banks are supported by the hardware. Supported for HC12 only. It is not recommended to use this feature, if there is no need to locate application into the banked memory. TRUE, FALSE OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Quick Reference 329 A G R E E M E N T Object Parameters N O N - D I S C L O S U R E Table E-6. OS Parameters R E Q U I R E D Quick Reference OIL language Quick Reference N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Quick Reference Table E-6. OS Parameters Object Parameters Description Notes TRUE, FALSE Defines that Alternative Register File will be used for ISR processing. This attribute is useful in case of numerous single-level interrupts most of which do not cause task re-scheduling. Also it allows to avoid problem of using variables inside ISR category 3, problem of nested interrupts for MCORE and problem of using normal interrupt exceptions for MCORE. Supported for MCORE only. This attribute, if it is TRUE, requires vector table adjusting. The low order bit of the exception vector content must be 1 for every vector in the table (except those ones that are not really used). TRUE, FALSE Simplified scheduler is used. This scheduler supports table of ready tasks unlike convenient scheduler, which supports list of ready tasks. The main restriction of this type of scheduler is that only one task per priority may be used (i.e., each task should has unique priority), and, hence, OSEK resources are not allowed. Also task multiply activations are not supported. However, the simplified scheduler requires less code, and runs much faster. In spite, that the features, provided by this type of scheduler, are suitable for BCC1, it may be used in any conformance class when the conditions, mentioned above, are met. It is highly recommended to use this type of scheduler, unless resources or/and several tasks per priority and task multiply activation are required in application. UseCommonArea TRUE, FALSE If this attribute is set to TRUE, stack usage is reduced for system services, and, hence for tasks and ISRs. In this case static memory area is used for parameters and local variables of system services. About 20 more bytes are required in RAM to hold common area, while code and timing is increased very slightly. It is recommended to use this feature, only if RAM requirements is an issue. In general, 20%-30% of task and ISR stack space is saved (see Section 15 HC12 PlatformSpecific Features for more information). CopyrightNotice TRUE, FALSE Specifies whether copyright notice should be incorporated into OS ROM code or not. It is highly recommended always have this attribute set to TRUE. Reconfig TRUE, FALSE This option allows to have a number of different application modes (different sets of tasks) in the same application.In this case it is possible to change application mode after system shutdown. If Reconfig is set to TRUE, then Extended OIL format should be used to define application modes. If it is not necessary to have a number of different application modes in the same application, then it is recommended to turn this property off. It decreases the needed amount of RAM for task identification and increases the speed. UseMoveBlockInstruction TRUE, FALSE Defines whether OS has to use CPU This attribute is intended for memory move block instructions or not. MPC only. HCAltRegISR SimpleScheduler Possible Values User's Manual 330 OSEK Operating System -- Rev 1.2 Quick Reference MOTOROLA Object Parameters Possible Values Description Notes Low Power Related Attributes These OS attributes associate with support Low Power Mode HCLowPower TRUE, FALSE Defines that the MCU Low Power Mode will be used instead of plain forever no-operation when there is no ready tasks, and scheduler goes into idle loop. In general, it is recommended to define this attribute to reduce power consumption. However, the recovery from the low power state to the normal conditions (after interrupt) may take more time, than recovery from normal loop. HCLowPowerMode WAIT, DOZE, STOP, NORMAL, SINGLE, SLEEP Defines the particular Low Power Mode used Supported for MPC and MCORE only. Applicable if HCLowPower = TRUE HCLowPowerMask TRUE, FALSE Defines whether the IRQ[0:1] pin mask is defined for Low Power exit logic or not Supported for MPC only HCLowPowerMaskValue NONE, IRQ Defines a mask for Low Power Exit logic Supported for MPC only. Applicable if HCLowPowerMask = TRUE Not supported for WINNT. System Memory Related Attributes This group of OS attributes associates with system memory allocation NodeNumber integer Specifies the number of task control blocks (nodes), allocated in the system. For every ready task separate control block should be used, therefore this value should be big enough to support all ready tasks. However, the same task control block may be used by several tasks, if they are not activated simultaneously. In general, the task control blocks are assigned dynamically to the task, when it is activated. In addition, several attributes may be used to provide persistent link between task and task control block. AUTO if undefined, and number of nodes will be equal to the number of tasks, defined in application. It is highly recommended to set this value explicitly to avoid overhead connected with consuming to much RAM for each task, which are not run in the same time. integer Specifies the number of task priorities. In general, there is no relations between number of task control blocks unless SimpleScheduler attribute is defined TRUE. In the last case these numbers should be equal. AUTO if undefined. In spite, that system generator compacts the priority range, it is highly recommended to keep the priority range as small as possible. This will make debugging easy. MaxPrio OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Quick Reference 331 N O N - D I S C L O S U R E Table E-6. OS Parameters A G R E E M E N T R E Q U I R E D Quick Reference OIL language Quick Reference N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Quick Reference Table E-6. OS Parameters Object Parameters UseMainStack SchedStackSize SchedStackAddress IsrStackSize IsrStackAddress Possible Values Description Notes TRUE, FALSE Use the same stack for system startup, scheduler, and ISRs. If turned FALSE, then separate stacks are used for system start-up code, for scheduler idle loop, and for interrupt service routines. In this case, the user may fully control the size and location of stack areas by means of using attributes, described below. However, the RAM requirements may be reduced if all these stacks are combined in the same memory area. As a side effect, the code size is slightly decreased, because stack switching is simplified. It is recommended to define this attribute unless there is special requirements to stack locations. However, the size of the stack should be controlled by user usually by means of using linker directives. The size of stack should be big enough to hold interrupt stack frames for the nested interrupts. integer Scheduler stack size in bytes. This stack is mainly used when scheduler goes into idle loop, when there is no ready tasks. This stack should be big enough to hold interrupt stack frame and several additional bytes. Ignored if UseMainStack=TRUE. string Scheduler stack address. This parameter may be used, if there is a need to allocate scheduler stack in particular memory section. (For example, internal MCU RAM may be used instead of external RAM to provide better timing). Ignored if UseMainStack=TRUE. If this parameter is set, then proper linking directives should be used to locate stack area at particular memory address. integer ISR Stack Size. The stack is used when interrupt service routine calls system service. In this case the current status of the processor is saved onto the current stack, and stack is switched to the interrupt stack. This stack should be big enough to hold all nested interrupt stack frames in the system. string ISR Stack Address. This parameter may be used, if there is a need to allocate ISR stack in particular memory section. (For example, internal MCU RAM may be used instead of external RAM to provide better timing or power consumption). User's Manual 332 Ignored if UseMainStack=TRUE. Ignored if UseMainStack=TRUE. If this parameter is set, then proper linking directives should be used to locate stack area at particular memory address. OSEK Operating System -- Rev 1.2 Quick Reference MOTOROLA Description Notes TRUE, FALSE Defines the support of task control block stacks in the operating system code. If this parameter is set to FALSE, some another stack mechanism (stack pool, static stack) should be configured to protect the system from crash due to lack of stack. AUTO if undefined. It is highly recommended to set this parameter to FALSE, if task control block stacks are not used by no one task. This way, both code size as well as RAM consumption will be decreased. integer Specifies the size of the stack (in bytes) per each task control block. In general, each task control block has its own stack with fixed size. Therefore, the simplest way is to define this attribute, and use task control block stack for ready tasks. However, the memory consumption is not optimized in this case, because every task may have different stack requirements. Ignored if NodeStack = FALSE. If any task control block may be used by any task, this parameter should be big enough to satisfy requirements of the task, which comsumes biggest stack. NodeStackAddress string Specifies the bottom of task control block stacks. This parameter may be used, if there is a need to allocate task control blocks stack array in particular memory section. (For example, to utilizes different areas of the RAM in the microcontroller memory map). Ignored if NodeStack = FALSE. The task control block stack area is allocated as continuous block of memory. ClearReservation TRUE, FALSE NodeStack NodeStackSize Possible Values Clears outstanding reservations between processes. This attribute is supported for MPC only. Task Related Attributes This group of OS attributes controls task feature MultiplyActivation The FALSE attribute disables task multiple activation. This feature is useful, if there is a need to have an extended conformance class, but to exclude multiple activation of the tasks. In this case the attribute decreases code size, and task control block size, as well as eliminates some variables, connected with tracking of order of task activations. TRUE, FALSE OSEK Operating System -- Rev 1.2 MOTOROLA Valid only if CC = BCC2, ECC2; AUTO if undefined. It is highly recommended to define this attribute unless multiple activation is required in the application. User's Manual Quick Reference 333 A G R E E M E N T Object Parameters N O N - D I S C L O S U R E Table E-6. OS Parameters R E Q U I R E D Quick Reference OIL language Quick Reference N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Quick Reference Table E-6. OS Parameters Object Parameters TaskIndexMethod StackPool PersistentNode Possible Values Description Notes TRUE, FALSE If this attribute is defined, then the intermediate vector of the pointers to the task control blocks for each task in the system is used to track the status of the task (activated or suspended). Therefore, fast and deterministic access to task control blocks is provided. However, more RAM space is required to hold the intermediate vector of pointers (one pointer for each task, configured in the application). It is recommended to set this attribute to TRUE, if more than 8 tasks are configured in the system, and there is a lot of task activations. However, this attribute should be set to FALSE, if SimpleScheduler= TRUE. TRUE, FALSE Defines whether stack pools are supported or not. The stack pools are useful when different set of tasks has different requirements for the stacks. In this case, the stack of needed size will be allocated for the task during the runtime. The distribution of the stack pools should be performed by the application developer. The tasks are to be grouped by the stack size required, stack pool for particular size should created, and then the number of stacks in each pool should be defined by means of calculating a number of tasks in each group activated at the same time. AUTO if undefined. Because the configuration of the stack pools is rather complicated task, therefore these pools are recommended for experienced users. TRUE, FALSE When set to TRUE, allows persistent task control block allocation. The persistent task control block is the control block, which is explicitly assigned (allocated) to the task. This persistent task control block improves the timing, because no run-time allocating/freeing of task node is required. However, the persistent task control block can not be used by any other task in application, even when the task is suspended. User's Manual 334 AUTO if undefined. The distribution of the persistent task control blocks is rather complicated task, therefore these pools are recommended for experienced users. OSEK Operating System -- Rev 1.2 Quick Reference MOTOROLA PersistentStack TaskOwnStack UseSameContext Possible Values TRUE, FALSE Description When set to TRUE, allows persistent task stack allocation. The persistent task stack is the stack from the stack pool, which is explicitly assigned (allocated) to the task. This persistent task stack improves the timing, because no run-time allocating/freeing of task stack is required. However, the persistent stack can not be used by any other task in application, even when the task is suspended. The task stack may be made persistent for the task, only if this task has persistent task node. AUTO if undefined. The distribution of the persistent stacks is rather complicated task, therefore these pools are recommended for experienced users. TRUE, FALSE When set to TRUE, allows the explicit task stack allocation. The explicit task stack is a static memory area, which is used by the task for stack. This feature improves the timing, because no dynamic operations are involved into the task activating/terminating. However, the stack memory area can not be used for any other tasks. AUTO if undefined. In spite, that same memory area may be used by several tasks, if only one of them is activated in the given time, it is recommended to avoid such configurations. The own stack of the task is the easiest way to watch the stack status, because it is absolutely clear where the stack is located. Therefore, it is recommended to use this feature if there are troubles, connected with the stack overflow. TRUE, FALSE Defines whether the some run-time context frame is used both for nonpreemptive and preemptive tasks. When set to TRUE, decreases code size and improves timing. However, more stack is required for nonpreemptive task context, because preemptive context is used for any task. Valid only if SCHEDULE=MIXED. It is highly recommended to set this attribute to TRUE. This simplifies debugging of the application. OSEK Operating System -- Rev 1.2 MOTOROLA Notes User's Manual Quick Reference 335 A G R E E M E N T Object Parameters N O N - D I S C L O S U R E Table E-6. OS Parameters R E Q U I R E D Quick Reference OIL language Quick Reference N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Quick Reference Table E-6. OS Parameters Object Parameters TaskBasePage ChainTaskItself Possible Values Description Notes TRUE, FALSE If TRUE, the task control blocks are allocated into the base page memory. It increases the system performance since CPU accesses the base page is faster than to the extended memory. In addition, code size is decreased. However, because base page has limited size, and may be used for application needs, the amount of memory, required to hold all task control blocks, should be estimated beforehand. Supported for HC08, HC12 for base page (address range 0016-FF16). It is recommended to use base page for task control block, if there is enough space in it. In this case, application should be linked correctly to provide proper allocation of data in base page. It is highly recommended to use sample makefile as a basis for using this attribute properly (in compiler/linker settings). However, some MCUs use base page for input-output registers, which prevents the using of it for variables. This attribute is completely independent from HCBasePage attribute, and any combinations of them may be used. TRUE, FALSE This parameter may be set to FALSE if there is no tasks that chain itself. It decreases the task control block size. It is highly recommended to set this parameter to TRUE unless there are tasks which chain itself. Extended Task Context Related Attributes This group of OS attributes controls task context extension ExtendedContext TRUE, FALSE Defines whether OS has to support task context extension or not. Valid only if the target MCU has the corresponding hardware support, or some virtual compiler registers are to be included into task context. NonPreemptCtxRegNum integer Specifies the number of extended registers included into non-preemptive task context. PreemptCtxRegNum integer Specifies the number of extended registers included into preemptive task context. User's Manual 336 Supported for MPC, CPU32, HC08 only. Supported for MPC, CPU32 only. Valid only if ExtendedContext = TRUE. These parameters allow experienced user to optimize task context depending on the application code and compiler behavior. It these parameters are not used and ExtendedContext = TRUE, then task context contains all extended registers. OSEK Operating System -- Rev 1.2 Quick Reference MOTOROLA SaveNonPreemptCtxExt RestoreNonPreemptCtxExt SavePreemptCtxExt RestorePreemptCtxExt Possible Values Description string Specifies the assembler macro for saving extended registers into nonpreemptive task context. It should be a STRING which contains inline assembler statements for saving extended registers string Specifies the assembler macro for restoring extended registers from nonpreemptive task context. It should be a STRING which contains inline assembler statements for restoring extended registers string Specifies the assembler macro for saving extended registers into preemptive task context. It should be a STRING which contains inline assembler statements for saving extended registers string Specifies the assembler macro for restoring extended registers from preemptive task context. It should be a STRING which contains inline assembler statements for restoring extended registers Interrupt Related Properties Supported for CPU32 only. Valid only if ExtendedContext = TRUE. These parameters allow experienced user to optimize task context depending on the application code and compiler behavior. It these parameters are not used and ExtendedContext = TRUE, then task context contains all extended registers. This group of OS attributes defines parameters of ISR execution EntryExitISR TRUE, FALSE Defines whether OS provides ISR support or not. In general, this attribute should be set to TRUE, if the application has interrupt service routines, which call system service. ISRCategory1 TRUE, FALSE Specifies whether the ISR of category 1 is supported by OS or not. Currently this attribute does not affect OS code. ISRCategory2 TRUE, FALSE Specifies whether the ISR of category 2 is supported by OS or not. Currently this attribute does not affect OS code. ISRCategory3 TRUE, FALSE Specifies whether the ISR of category 3 is supported by OS or not. OSEK Operating System -- Rev 1.2 MOTOROLA Notes If no ISR which call system service are used in the application, it is recommended to set this attribute to FALSE. This will decrease the code size and will improve timing, because no interrupt-level checks are performed in the system. User's Manual Quick Reference 337 A G R E E M E N T Object Parameters N O N - D I S C L O S U R E Table E-6. OS Parameters R E Q U I R E D Quick Reference OIL language Quick Reference N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Quick Reference Table E-6. OS Parameters Object Parameters Possible Values Description Notes InterruptMaskControl TRUE, FALSE Defines whether OS provides the Interrupt Mask Control or not. If this attribute is set to TRUE, the user is allowed to use interrupt descriptor manipulation services. Besides, the system always tracks the status of interrupts during the system service execution. That means, that application has full control on the interrupt status. For example, the task may disable interrupts, call system service, and interrupts will be disabled when service will be completed. When this parameter is set to FALSE, interrupts will be re-enabled in this scenario after system service completion. In addition, no interrupt descriptor manipulation services are allowed. When this attribute is set to TRUE, code size and timing is significantly increased. DisableInterruptMask integer Specifies the value of Interrupt mask which corresponds to all interrupts disabled. EnableInterruptMask integer Specifies the value of Interrupt mask which corresponds to all interrupts enabled integer Specifies the value of Interrupt mask which corresponds to the middle level of enabled interrupts for tasks in the system integer Specifies the value of Interrupt mask which corresponds to the initial level of enabled interrupts during the system start-up TaskLevelMask InitialMask User's Manual 338 The full control of interrupt status is designed for processors having complex interrupt masks (like HC16 or CPU32). It is highly recommended to set this attribute to FALSE for processors which have rather simple interrupt system (like HC08 or HC12). It should be double checked, that all interrupt masks (including interrupts masks for each task) are defined properly if this attribute is set to TRUE. Valid only if InterruptMaskControl=TRUE. The exact value for the particular platform is described in other section of this manual. As a general rule, the bit position in these mask should correspond to the interrupt(s) bits in CPU conditional code or flags registers with value one represented enable state, and value zero represented disable state. OSEK Operating System -- Rev 1.2 Quick Reference MOTOROLA Possible Values Description integer Specifies the number of extended registers to be saved into ISR stack frame. It should contain value from 1 till 18 string Specifies the assembler macro for saving extended registers into ISR stack frame. It should be a STRING which contains inline assembler statements for saving extended registers RestoreISRCtxExt string Specifies the assembler macro for restoring extended registers from ISR stack frame. It should be a STRING which contains inline assembler statements for restoring extended registers UnorderedExceptions TRUE, FALSE Allow unordered exception handling. ISRCtxRegNum SaveISRCtxExt Notes Intended for MPC505 only, not implemented yet. Valid only if ExtendedContext = TRUE. These parameters allow experienced user to optimize ISR context depending on the application code and compiler behavior. If these parameters are not used and ExtendedContext = TRUE, then ISR stack frame contains all extended registers. This attribute is intended for MPC only. Resources and Events Related Attributes These OS attributes control resources and events Events TRUE, FALSE Defines whether event management is provided by OS or not. Set this attribute to be FALSE to exclude event support. If the attribute is set as FALSE then no event services will be available in the application TRUE, FALSE Defines whether resource management is provided by OS or not. Set this attribute to be FALSE to exclude resource support. If the attribute is set as FALSE then no resource services will be available in the application. Resources FastResource ResourceAccessCheck AUTO if undefined. TRUE, FALSE Defines whether fast resources are provided by OS or not. If it is TRUE the system will work faster. This option is strongly recommended only for debugged applications, because errors related to incorrect access and priority are not signaled to the application. TRUE, FALSE Defines whether E_OS_ACCESS error code is returned by GetResource service or not. If it is TRUE, then error code will be returned in EXTENDED status based on task definition in OILfile. If system has STANDARD status or FastResource property turned on or more than 8 resources (including Scheduler) are defined in application, then this property should be set to FALSE. Counters and Alarms Related Attributes This group of OS attributes controls counters and alarms features OSEK Operating System -- Rev 1.2 MOTOROLA AUTO if undefined. User's Manual Quick Reference 339 A G R E E M E N T Object Parameters N O N - D I S C L O S U R E Table E-6. OS Parameters R E Q U I R E D Quick Reference OIL language Quick Reference N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Quick Reference Table E-6. OS Parameters Object Parameters Counters CounterSize Alarms AlarmList Possible Values TRUE, FALSE 8, 16, 32 TRUE, FALSE TRUE, FALSE Description Defines whether counters are provided by OS or not. Set this attribute to be FALSE to exclude alarm support. If the attribute is set as FALSE then no counter connected services will be available in the application. The system timer is not supported if this attribute is set to FALSE. Defines the size of all counters. The valid values are 8, 16 and 32 which conform to byte, word and long word size of counters. It is highly recommended to use minimal counter size in the application to decrease code size and improve timing. In general, 8-bits counters should be used for 8-bits CPUs (like HC08), 16-bits counters should be used for 16-bits CPUs (like HC12), while 32-bits counters may be used in CPU32, MPC and MCORE. This size is defined for all counters in the application. Defines whether alarms are supported by OS or not. Set this attribute to be FALSE to exclude alarm support. If the attribute is set as FALSE then no alarm services will be available in the application. If the attribute is TRUE the running alarms are linked into a list which decreases the time for alarm handling. If this attribute and AlarmDeltaList attribute are FALSE, table of alarms is used. The list of alarms improves timing of alarms operation, especially if dozen of alarms are used in the system. However, list of alarms requires much more memory than table of alarms to support lists. The setting of this attribute should be balanced between timing and memory requirements. User's Manual 340 Notes OSEK Operating System -- Rev 1.2 Quick Reference MOTOROLA AlarmDeltaList CyclicAlarm MinAlarmRAM Possible Values TRUE, FALSE TRUE, FALSE TRUE, FALSE Description Notes If the attribute is TRUE the running alarms are linked into a ordered alarm delta-list which decreases the time for CounterTrigger() service if too much alarms are connected to the same counter. If this attribute and AlarmList attribute are FALSE, table of alarms is used. The delta-list of alarms improves timing of CounterTrigger() service, especially if dozen of alarms are connected to the same counter. However, deltalist of alarms requires much more memory than table of alarms to support lists also timing of alarm management services like SetAbsAlarm(), SetRelAlarm() and GetAlarm() will be increased. The setting of this attribute should be balanced between timing and memory requirements. Only one of the options AlarmList and AlarmDeltaList may be used in the application. Defines whether alarms are supported by OS or not. When FALSE no one alarm may be cyclic (this decreases RAM usage for alarm control blocks and for task stacks, as well as decreases code usage and advances timing of alarms services). Defines whether the alarm handling is optimized for memory (RAM) or not. When FALSE alarm handling is optimized for speed. When turned on, the alarm control block is significantly decreased, because most information is stored into ROM. This decreasing is especially significant when AlarmList attribute is set to FALSE. System Timer Related Attributes These are additional OS attributes to tune the selected hardware interrupt source SysTimer Defines whether the System Timer is provided by OS or not. TRUE, FALSE OSEK Operating System -- Rev 1.2 MOTOROLA Valid only if interrupt related services are supported by OS, i.e. if EntryExitISR = TRUE. User's Manual Quick Reference 341 A G R E E M E N T Object Parameters N O N - D I S C L O S U R E Table E-6. OS Parameters R E Q U I R E D Quick Reference OIL language Quick Reference N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Quick Reference Table E-6. OS Parameters Object Parameters Possible Values Description Notes TimerHardware TIMTOI, TIMOC0, TIMOC1, TIMOC2, TIMOC3, TIMOC4, TIMOC5, TIMOC6, TIMOC7, TIMATOI, TIMAOC0, TIMAOC1, TIMAOC2, TIMAOC3, TIMBTOI, TIMBOC0, TIMBOC1, RTI, PIT, DEC, MDC, CTM4S1FCSM, CTM4S1MCSM2, CTM4S1MCSM11, CTM4S2FCSM, CTM4S2MCSM2, CTM4S2MCSM11, NTTIMER1 This attribute is intended to select the hardware interrupt source for the system counter (among the accessible MCU devices) This parameter can not be omitted, if system timer is defined (except OSEK OS/NT). Prescaler TRUE, FALSE Defines if the Prescaler is to be set for the selected System Timer hardware. PrescalerValue integer Defines the Prescaler setting for the selected System Timer hardware. TimerModulo TRUE, FALSE Defines if the Modulo is to be set for the selected System Timer hardware. TimerModuloValue integer Defines the Modulo setting for the selected System Timer hardware. The value of this attribute is fully hardware-dependent. The value of this attribute is fully hardware-dependent. Messages Related Attributes These are additional OS attributes to control local messages UnqueuedMessages TRUE, FALSE Set this attribute as FALSE to exclude Unqueued Messages support for the system. If the attribute is set to be FALSE then all Unqueued Message related services will be unavailable in the application. TRUE, FALSE Set this attribute as TRUE to allow Unqueued Messages to have default values. AUTO if undefined. If the attribute is set to be FALSE then Ungueued Messages will not be able to have default values. TRUE, FALSE Set this attribute as FALSE to exclude Queued Messages support in the system. If the attribute is set to be FALSE then all Queued Message related services will be unavailable in the application. UnqueuedMsgDefaultValue QueuedMessages User's Manual 342 OSEK Operating System -- Rev 1.2 Quick Reference MOTOROLA Possible Values Description Notes AUTO if undefined. If the attribute is set to be FALSE then 1:N Queued Messages are not supported for the application. QueuedMessageOneToN TRUE, FALSE Set this attribute as FALSE to exclude 1:N Queued Messages support in the system. ActivateOnMsg TRUE, FALSE If the attribute is TRUE then the task activation on message arrival is supported for the application. AUTO if undefined. TRUE, FALSE If the attribute is TRUE then the alarm notification on message arrival is supported for the application (an alarm can be linked to message arrival). AUTO if undefined. TRUE, FALSE If the attribute is TRUE then the event notification on message arrival is supported for the application (an event setting is allowed on message arrival). AUTO if undefined. AlarmOnMsg SetEventOnMsg Hook Routines Related Attribute This OS attribute defines additional hook routines support in the system TRUE, FALSE Defines whether the internal error handler is implemented in OS or not. Internal error handler is used to catch fatal errors of the operating system. The error hook is called independently of this parameter setting. IdleLoopHook TRUE, FALSE Defines that user's-provided hook is called by the Operating System from scheduler idle loop (when there are no tasks in ready state). This hook is intended for manipulation with hardware registers (like COP). It is not possible to call any OSEK OS directives from this hook. UserCommand1 string The attribute defines entry point of the user's command hook #1 to be called from the OS Dispatcher thread. InternalErrorHandler UserCommand2 string The attribute defines entry point of the user's command hook #2 to be called from the OS Dispatcher thread. UserCommand3 string The attribute defines entry point of the user's command hook #3 to be called from the OS Dispatcher thread. OS Service Related Attributes The group of attributes is designed to exclude particular OS services. If an attribute is FALSE the corresponding service is excluded from the OS code. Names of these attributes are the same as corresponding OS service names OSEK Operating System -- Rev 1.2 MOTOROLA Supported for OS/NT with interrupt emulation only. It is possible to call Windows library functions from this hooks. Special mechanism to invoke hooks should be used. User's Manual Quick Reference 343 A G R E E M E N T Object Parameters N O N - D I S C L O S U R E Table E-6. OS Parameters R E Q U I R E D Quick Reference OIL language Quick Reference N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Quick Reference Table E-6. OS Parameters Object Parameters Possible Values ShutdownOS TRUE, FALSE GetActiveApplicationMode TRUE, FALSE ActivateTask TRUE, FALSE TerminateTask TRUE, FALSE ChainTask TRUE, FALSE Schedule TRUE, FALSE GetTaskId TRUE, FALSE GetTaskState TRUE, FALSE GetTCBInfo2 TRUE, FALSE GetResource TRUE, FALSE ReleaseResource TRUE, FALSE GetScheduler TRUE, FALSE ReleaseScheduler TRUE, FALSE SetEvent TRUE, FALSE ClearEvent TRUE, FALSE GetEvent TRUE, FALSE WaitEvent TRUE, FALSE EnterISR TRUE, FALSE LeaveISR TRUE, FALSE EnableInterrupt TRUE, FALSE DisableInterrupt TRUE, FALSE GetInterruptDecsriptor TRUE, FALSE InitCounter TRUE, FALSE CounterTrigger TRUE, FALSE AdvanceCounter2 TRUE, FALSE GetCounterValue TRUE, FALSE GetCounterInfo TRUE, FALSE Description Set this attribute as FALSE to exclude code supporting the corresponding OS service. This will decrease the total OS code size. If the attribute is set to be FALSE then the service will be unavailable in the application. Set this attribute as FALSE to exclude code supporting the corresponding OS service. This will decrease the total OS code size. If the attribute is set to be FALSE then the service will be unavailable in the application. Exclude Execution Control services. Exclude Task services. Set this attribute as FALSE to exclude code supporting the corresponding OS service. This will decrease the total OS code size. If the attribute is set to be FALSE then the service will be unavailable in the application. Exclude Resource services. Set this attribute as FALSE to exclude code supporting the corresponding OS service. This will decrease the total OS code size. If the attribute is set to be FALSE then the service will be unavailable in the application. Exclude Event services. Set this attribute as FALSE to exclude code supporting the corresponding OS service. This will decrease the total OS code size. If the attribute is set to be FALSE then the service will be unavailable in the application. Exclude ISR services. Set this attribute as FALSE to exclude code supporting the corresponding OS service. This will decrease the total OS code size. If the attribute is set to be FALSE then the service will be unavailable in the application. Exclude Counter services. User's Manual 344 Notes OSEK Operating System -- Rev 1.2 Quick Reference MOTOROLA Object Parameters Possible Values SetRelAlarm TRUE, FALSE SetAbsAlarm TRUE, FALSE CancelAlarm TRUE, FALSE GetAlarm TRUE, FALSE GetAlarmBase TRUE, FALSE SendMessage TRUE, FALSE ReceiveMessage TRUE, FALSE GetMessageResource TRUE, FALSE ReleaseMessageResource TRUE, FALSE GetMessageStatus TRUE, FALSE Description Notes Set this attribute as FALSE to exclude code supporting the corresponding OS service. This will decrease the total OS code size. If the attribute is set to be FALSE then the service will be unavailable in the application. Exclude Alarm services. Set this attribute as FALSE to exclude code supporting the corresponding OS service. This will decrease the total OS code size. If the attribute is set to be FALSE then the service will be unavailable in the application. Exclude Messaging services. 1. NTTIMER may be omitted for OSEK OS/NT. 2. This service is not defined in the OSEK OS v.2.0 rev. 1 specification. This is an extension of OSEK OS. E.3.2 TASK Object Parameters of this object type define task properties. The TASK object has the standard and Motorola's specific attributes and references. Table E-7. TASK Parameters Object Parameters Possible Values Description Notes Standard Attributes PRIORITY integer Defines the priority of the task. The higher task priority corresponds to the higher PRIORITY value TYPE BASIC, EXTENDED Defines the task type SCHEDULE FULL, NON Defines the run-time behavior of the task AUTOSTART TRUE, FALSE Defines whether the task is activated during the system start-up procedure or not ACTIVATION integer The maximum number of registered activation requests for the task In the Motorola's implementation value range is [0...255] The value range is [1...255] Motorola's Specific Attributes OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Quick Reference 345 N O N - D I S C L O S U R E Table E-6. OS Parameters A G R E E M E N T R E Q U I R E D Quick Reference OIL language Quick Reference N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Quick Reference Table E-7. TASK Parameters Object Parameters Possible Values Description Notes MemoryBank integer Defines the memory bank for the task code. It should be defined only if memory banking is used InterruptMask integer Defines the starting task's interrupt mask PersistentNode TRUE, FALSE If the attribute is set as TRUE a persistent task node is assigned to the task If this parameter is omitted, then OS TaskLevelMask value is used NODESTACK, POOLSTACK, OWNSTACK Specifies the stack allocation method for the task NODESTACK - stack is assigned statically in the Node Stack system area. POOLSTACK - stack is assigned dynamically in the pointed stack pool. OWNSTACK stack is explicitly assigned by the user integer Defines the size of the task stack in bytes. It depends on the CPU family and functionality of the task Shall be defined only when the StackMethod value is OWNSTACK StackAddress string Task stack address. This parameter may be used, if there is a need to allocate task own stack in particular memory section. (For example, internal MCU RAM may be used instead of external RAM to provide better timing). Valid ifStackMethod=OWNSTACK. If this parameter is set, then proper linking directives should be used to locate stack area at particular memory address. PersistentStack TRUE, FALSE If the attribute is set as TRUE a persistent stack buffer is assigned to the task Valid if StackMethod = POOLSTACK RESOURCE names of RESOURCEs Resources accessed by task EVENT names of EVENTs Events owned by the task StackMethod STACKSIZE Motorola's Specific Attribute Standard References Motorola's Specific References MESSAGESENT names of MESSAGEs Reference to messages which are sent by the task MESSAGERECEIVED names of MESSAGEs Reference to messages which are consumed by the task User's Manual 346 OSEK Operating System -- Rev 1.2 Quick Reference MOTOROLA Table E-7. TASK Parameters Object Parameters Possible Values StackPool name of STACK Description Notes If a task uses the stack from a stack pool the reference to the dedicated stack pool must be provided. The symbolic name of the stack pool shall be pointed E.3.3 ISR Object This object represents an Interrupt Service Routine. Parameters of this object type define ISR properties. The ISR object has the standard attributes and references. Table E-8. ISR Parameters Object Parameters Possible Values Description Notes Standard Attribute CATEGORY 1, 2, 3 In OSEK OS three categories of ISR are considered depending on system services used FAST, NORMAL Chooses the type of ISR. ISR can be launched by Fast Interrupt exception or normal exception Motorola's Specific Attribute TYPE Supported for MCORE only, HCAltRegISR shall be TRUE MESSAGESENT names of MESSAGEs N O N - D I S C L O S U R E Motorola's Specific Reference Reference to messages which are sent by ISR E.3.4 STACK Object The STACK object defines physical parameters of a stack pool This object is Motorola's specific object and it has no standard attributes. Table E-9. STACK Parameters Object Parameters Possible Values Description Notes Motorola's Specific Attributes StackSize integer Represents the size of a single stack buffer NumberOfStacks integer Defines the number of stack buffers in the pool OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Quick Reference A G R E E M E N T R E Q U I R E D Quick Reference OIL language Quick Reference 347 N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Quick Reference Table E-9. STACK Parameters Object Parameters StackAreaAddress Possible Values Description Notes Specifies the start address of the pool memory area. This optional parameter serves for explicit memory allocation for the task stack pool string E.3.5 RESOURCE Object The RESOURCE object is intended for the resource management. This object has no standard attributes and references. Table E-10. RESOURCE Parameters Object Parameters Possible Values Description Notes Motorola's Specific Attribute PRIORITY Defines the resource priority. The higher value corresponds to the higher priority integer AUTO if undefined E.3.6 ALARM Object This object presents OS alarms. The ALARM object has the standard attributes and references. Table E-11. ALARM Parameters Object Parameters Possible Values Description Notes Standard Attribute ACTIVATETASK, SETEVENT Defines which type of task notification is used when the alarm expires COUNTER name of COUNTER Points to a particular counter to have an ability to operate TASK name of TASK Points to a task which is to be notified via activation or event setting when the alarm expires ACTION Standard References EVENT name of EVENT Point to an event which is to be set when the alarm expires User's Manual 348 The event is considered as an inseparable pair of the task and the event belonging to this task, so the reference to the task which owns the events shall be also defined for this alarm OSEK Operating System -- Rev 1.2 Quick Reference MOTOROLA Table E-12. COUNTER Parameters Object Parameters Possible Values Description Notes Standard Attributes MAXALLOWEDVALUE integer Defines the maximum allowed counter value MINCYCLE integer Specifies the minimum allowed number of counter ticks for a cyclic alarm linked to the counter TICKSPERBASE integer Specifies the number of ticks required to reach a counter-specific value Motorola's Specific Attribute SystemTimer TRUE, FALSE Specifies whether the counter is the system timer TICKDURATION integer Specifies duration of a tick of the system counter in nanoseconds By default this attribute has the value FALSE. Note, however, that only one counter must be defined as the system timer Shall be defined for system counter only E.3.8 MESSAGE Object Parameters of this object type define message properties. The MESSAGE object has the Motorola's specific parameters at the moment. Some of them are proposed to be standard attributes. By convention the parameters of this object can be divided into two groups: standard and Motorola's specific parameters. Table E-13. MESSAGE Parameters Object Parameters Possible Values Description Notes Standard Attributes TYPE UNQUEUEDMESSAGE, QUEUEDMESSAGE Queued message data is buffered and consumed by receive operations. Unqueued message data is not consumed and overwritten each time OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Quick Reference 349 A G R E E M E N T Attributes of this object type define counter properties. A COUNTER object has no references, it is referenced to by other object. The COUNTER object has the standard and Motorola's specific attributes. N O N - D I S C L O S U R E E.3.7 COUNTER Object R E Q U I R E D Quick Reference OIL language Quick Reference N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Quick Reference Table E-13. MESSAGE Parameters Object Parameters Possible Values Description Notes ITEMTYPE string ITEMTYPE is the C data type of the message item. Define any ANSI-C typespecifier ITEMS integer The number of items has a sense only for Queued message, Unqueued message always has only one item ALARMRESETTIME integer Assigned alarm will be restarted with the specified time period at the message arrival ACTION ACTIVATETASK, SETEVENT, NONE Defines which type of task notification is used when the message arrives Valid if ALARMRESET reference is defined Motorola's Specific Attributes integer Defines the number of local task-receivers of the message. If it has a value greater than 1, then it is assumed, that several tasks may receive a message item from the Message queue TRUE, FALSE Specifies whether the alarm referenced by the message must be restarted during system start-up or not (default). Alarm restarting is used to trap the loss of the first message string Presents the address of the ROM-based variable, which holds the default value of the Unqueued message. This variable must have the type <ITEMTYPE>, and must be located in the user's code ALARMRESET name of ALARM Assigned alarm will be restarted with defined time period at the message arrival TASK name of TASK Task activation or event setting can be used to inform the specified task at message arrival ReceiverNum StartupAlarm DefaultValue Intended for unqueued messages only. The attribute may be omitted Standard References EVENT name of EVENT Event signaling can be used to inform the specified task at message arrival User's Manual 350 The event is considered as an inseparable pair of the task and the event belonging to this task, so the reference to the task which owns the events shall be also defined for this message OSEK Operating System -- Rev 1.2 Quick Reference MOTOROLA E.3.9 EVENT Object The EVENT object is intended for the event management. This object has no references. Table E-14. EVENT Parameters Object Parameters Possible Values Description Notes Standard Attribute integer Represents the event AUTO if undefined N O N - D I S C L O S U R E A G R E E M E N T MASK R E Q U I R E D Quick Reference OIL language Quick Reference OSEK Operating System -- Rev 1.2 MOTOROLA User's Manual Quick Reference 351 N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Quick Reference User's Manual 352 OSEK Operating System -- Rev 1.2 Quick Reference MOTOROLA Index B Basic Task 32, 43 BCC1 33 BCC2 33 C Ceiling Priority 87 CFG 168 CFGACTIVE 168 Conformance Class 32 conversion constant 94 COUNTER 162, 349 MAXALLOWEDVALUE 162 MINCYCLE 162 SystemTimer 163 TICKDURATION 162 TICKSPERBASE 162 CPU 138 E ECC1 33 ECC2 33 EVENT 161, 351 MASK 161 F fatal errors 126 H hook routines 121 I Interrupt Service Routine (ISR) 73 interrupt stack frame 75 ISR 167, 347 CATEGORY 167 MESSAGESENT 167 TYPE 167 ISR frame 73 M MESSAGE 164, 349 ACTION 164 ALARMRESET 166 ALARMRESETTIME 165 DefaultValue 166 EVENT 166 ITEMS 165 ITEMTYPE 165 ReceiverNum 166 StartupAlarm 165 TASK 166 TYPE 165 WithCopy 166 OSEK Operating System -- Rev 1.2 MOTOROLA A G R E E M E N T ALARM 163, 348 ACTION 163 COUNTER 163 EVENT 164 TASK 163 alarm 97 Application configuration file 134 Application Modes 168 event 105 Extended OIL version 135 Extended Status 37, 125, 127, 193 Extended Task 32, 41 N O N - D I S C L O S U R E A User's Manual Index R E Q U I R E D User's Manual -- OSEK Operating System 353 N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Index Message Objects (MO) 111 mild errors 126 multiple activation 34, 44 GetMessageStatus 156 GetResource 155 GetTaskId 155 GetTaskState 155 GetTCBInfo 155 HCAltRegISR 143 HCBankCode 143 HCBasePage 143 HCLowPower 144 HCLowPowerMode 144 IdleLoopHook 154 InitCounter 155 InitialMask 150 InternalErrorHandler 154 InterruptMaskControl 145 ISRCategory1 150 ISRCategory2 150 ISRCategory3 150 ISRCtxRegNum 150 IsrStackAddress 149 IsrStackSize 149 LeaveISR 155 MaxPrio 145 MinAlarmRAM 153 MultiplyActivation 147 NodeNumber 145 NodeStack 147 NodeStackAddress 146 NodeStackSize 145 NonPreemptCtxRegNum 148 OSVERSION 142 PersistentNode 148 PersistentStack 148 PostTaskHook 154 PreemptCtxRegNum 149 Prescaler 153 PrescalerValue 153 PreTaskHook 154 QueuedMessages 153 QueuedMsgOneToN 153 ReceiveMessage 156 Reconfig 146 ReleaseMessageResource 156 O OIL 134 ORTI 269 OS 142, 326 ActivateOnMsg 153 ActivateTask 155 AdvanceCounter 155 AlarmDeltaList 152 AlarmList 152 AlarmOnMsg 154 Alarms 152 CancelAlarm 156 CC 143 ChainTask 155 ChainTaskItself 148, 155 ClearEvent 155 CopyrightNotice 146 Counters 152 CounterSize 152 CounterTrigger 155 CyclicAlarm 152 DisableInterrupt 155 DisableInterruptMask 150 EnableInterrupt 155 EnableInterruptMask 150 EnterISR 155 EntryExitISR 145 ErrorHook 154 Events 152 ExtendedContext 147 FastResource 151 GetActiveApplicationMode 156 GetAlarm 156 GetAlarmBase 156 GetCounterInfo 155 GetCounterValue 155 GetEvent 155 GetInterruptDecsriptor 155 GetMessageResource 156 User's Manual 354 OSEK Operating System -- Rev 1.2 Index MOTOROLA UseSameContext 148 WaitEvent 155 OSEK 21 OSEK Implementation Language 134 OSEK Run Time Interface 269 OSShutDown 126 P Priority Ceiling Protocol 87 Queued Messages 111 R ready state 41, 43 RESOURCE 160, 348 PRIORITY 161 run time context 40 running state 41, 43 S scheduler 39, 65 simplified scheduler 66 single activation 44 STACK 159, 347 NumberOfStacks 160 StackAreaAddress 160 StackSize 160 Stack Errors 195 Standard OIL version 135 Start-up Routine 128 System Generator 36 System Generator utility (SG) 133 system timer 95 T TASK 156, 345 ACTIVATION 157 AUTOSTART 157 EVENT 159 InterruptMask 158 OSEK Operating System -- Rev 1.2 MOTOROLA A G R E E M E N T Q N O N - D I S C L O S U R E ReleaseResource 155 ResourceAccessCheck 151 Resources 151 RestoreISRCtxExt 151 RestoreNonPreemptCtxExt 149 RestorePreemptCtxExt 149 SaveISRCtxExt 150 SaveNonPreemptCtxExt 148 SavePreemptCtxExt 149 SchedStackAddress 145 SchedStackSize 145 SCHEDULE 147 Schedule 155 SendMessage 156 SetAbsAlarm 156 SetEvent 155 SetEventOnMsg 154 SetRelAlarm 156 ShutdownHook 154 ShutdownOS 156 SimpleScheduler 144 StackPool 148 StartupHook 154 STATUS 144 SysTimer 153 TargetMCU 142 TaskBasePage 148 TaskIndexMethod 147 TaskLevelMask 150 TaskOwnStack 148 TerminateTask 155 TimerHardware 153 TimerModulo 153 TimerModuloValue 153 UnorderedExceptions 151 UnqueuedMessages 153 UnqueuedMsgDefaultValue 153 UseCommonArea 146 UseMainStack 144 UseMoveBlockInstruction 147 UserCommand1 155 UserCommand2 155 UserCommand3 155 R E Q U I R E D Index User's Manual Index 355 MemoryBank 158 MESSAGERECEIVED 159 MESSAGESENT 159 PersistentNode 158 PersistentStack 158 PRIORITY 157 RESOURCE 159 SCHEDULE 157 StackMethod 157 StackPool 159 STACKSIZE 157 TYPE 156 task configuration table 40 task control block 51 task node 40 U Unqueued Messages 111 W waiting state 32, 105 N O N - D I S C L O S U R E A G R E E M E N T R E Q U I R E D Index User's Manual 356 OSEK Operating System -- Rev 1.2 Index MOTOROLA