220841977 enea ose epsilon arm kernel user s guide
TRANSCRIPT
AR
M K
erne
l
Enea Embedded Technology
2
2OSE Epsilon
ARM Kernel
User’s Guide
EArmKrnUG4.6
AR
M K
erne
l
OSE Epsilon/ ARM Kernel
CopyrightCopyright © 2005 by Enea Embedded Technology. All rights reserved. No part of this publication may be reproduced, transmitted, stored in a retrieval system, or translated into any language or computer language, in any form or by any means, electronic, mechanical, optical, chemical or otherwise, without the prior written permission of Enea Embedded Technology. If, however, your only means of access is electronic, permission to print one paper hardcopy is hereby granted. The software described in this document is furnished under a licence agreement or a non-disclosure agreement. The software may be used or copied only in accordance with terms of agreement.
DisclaimerEnea Embedded Technology makes no representations or warranties with respect to the contents hereof and specifically disclaims any implied warranties of merchantability or fitness for any particular purpose. Further, Enea Embedded Technology reserves the right to revise this publication and to make changes from time to time in the contents hereof without obligation to Enea Embedded Technology to notify any person of such revision or changes.
TrademarksOSE is a registered trademark of Enea Embedded Technology
Last modified: 20 December 2005
AR
M K
erne
l
User’s Guide / 4.6 Contents • 3
2
2
Contents1 Introduction 7
2 Introduction to OSE 92.1 Definition of an RTOS 102.2 Purpose of an RTOS 102.3 Real-Time Operating System Tasks 10
2.3.1 Resource Management 112.3.2 Time Management 112.3.3 Interprocess Communication 112.3.4 Speed Considerations 12
2.4 OSE Design Benefits 122.5 Concurrent Processes 12
2.5.1 Process States 132.5.2 Priority Based Process Scheduling 142.5.3 Round-Robin Process Scheduling 14
2.6 Process Categories in OSE 162.7 Process Types in OSE 16
2.7.1 Prioritized Processes 172.7.2 Background Processes 172.7.3 Interrupt Processes 172.7.4 Interrupt Performance 182.7.5 Timer Interrupt Processes 19
2.8 OSE Operating System Tools 192.8.1 Messages 20
2.8.1.1 Message Passing Through Mailboxes 202.8.1.2 Direct Message Passing in OSE 21
2.8.2 Fast Semaphores 222.8.3 Semaphores 23
3 Getting Started 253.1 Example System Description 263.2 Step by Step Tutorial 28
3.2.1 Equipment 293.2.2 Preparation 303.2.3 OSE Configuration 303.2.4 Getting the System Files 333.2.5 Getting Specific Drivers 333.2.6 Getting the Example Source Files 343.2.7 Building the System with ARM ADS 353.2.8 Building the System with IAR EWB 363.2.9 Building the System with GNU GCC 373.2.10 Running the System without OSE Illuminator 403.2.11 Running the System with OSE Illuminator 403.2.12 Debugging 42
3.2.12.1 Epsilon Debug Server 423.2.12.2 Debugging with OSE Illuminator 42
AR
M K
erne
l
4 • Contents User’s Guide / 4.6
4 Configuring OSE Epsilon for ARM 434.1 C Compiler 454.2 Target Name 464.3 CPU Type 474.4 Memory Model 484.5 Debug Option 494.6 Buffer Check Option 504.7 Stack Check Option 514.8 Option Debugger 524.9 Option Conditional Halt 534.10 Option Dispatcher in RAM 544.11 Pool Size 554.12 Buffer Sizes 564.13 Interrupt Stack 574.14 Temporary Stack 584.15 Error Handler 594.16 Start Handlers 604.17 Swap Handler 614.18 Send Handler 624.19 Receive Handler 634.20 Power On Handler 644.21 Power Off Handler 654.22 Idle Handler 684.23 Fast interrupts as IRQ:s 694.24 Interrupt Processes 704.25 Timer Interrupt Processes 714.26 Prioritized Processes 724.27 Link Handler Processes 734.28 Background Processes 744.29 Enable Wake Up 75
5 Building a System 775.1 System Files 795.2 Configuration 795.3 Configuration Utility 795.4 Illuminator System Level Debugger 795.5 Assembly-Time Errors 80
6 System Design 816.1 System Creation Cycle 836.2 Processes 84
6.2.1 Prioritized Processes 856.2.2 Background Processes 866.2.3 Interrupt Processes 876.2.4 Timer Interrupt Processes 886.2.5 Selecting Process Type 896.2.6 Process Include Files 906.2.7 Process Declarations in C 91
6.2.7.1 Prioritized and Background Processes 916.2.7.2 Interrupt and Timer-Interrupt Processes 91
6.2.8 Process Declarations in Assembler 92
AR
M K
erne
l
User’s Guide / 4.6 Contents • 5
2
2
6.2.8.1 Prioritized and Background Processes 926.2.8.2 Interrupt and Timer-Interrupt Processes 92
6.2.9 Process Design Rules 936.3 Starting and Stopping Processes 936.4 Signals 94
6.4.1 Using Signals In Processes 956.4.2 Buffer Transfer 96
6.5 Fast Semaphores 976.6 Semaphores 976.7 Memory Utilisation 98
6.7.1 Global Variables 986.7.2 Memory Requirements 99
6.7.2.1 Memory Used By the Buffer Pool 996.7.2.2 Memory Required By Stacks 996.7.2.3 Memory requirements 100
6.8 Speed Considerations 1026.8.1 Task Switch Performance 1026.8.2 Timer-Interrupt Process Frequency 1026.8.3 Signal Transmission Performance 1036.8.4 Interrupt Handling Performance 1036.8.5 Time Consumption of Other Functions 103
6.9 System Start 1046.10 Writing the Interrupt Handler 104
6.10.1 Sample Interrupt Handler 1046.10.2 Nested OSE Interrupts 1046.10.3 Interrupt Enable/Disable Functions 105
6.11 Writing a Link Handler 1066.11.1 Multiple Physical Links 1076.11.2 Buffer Structure 1076.11.3 Reformatting Buffers 107
6.12 Writing an Error Handler 1086.12.1 Error Information 1086.12.2 Continuing After an Error 110
7 Illuminator Debugger 1117.1 Serial Line Connection 112
7.1.1 System Configuration 1137.1.2 Testing the Target Debug Connection 1147.1.3 Epsilon Debug Server 115
7.2 Symbolic Signal Information 116
8 Timeout Server 1178.1 Request Timeout 1188.2 Cancel Timeout 1198.3 Retrigger Timeout 119
9 Glossary 121
AR
M K
erne
l
6 • Contents User’s Guide / 4.6
AR
M K
erne
l
User’s Guide / 4.6 Introduction • 7
2
2
1 IntroductionOSE for ARM is a fast, compact, real-time operating system for the ARM (Thumb) line of microprocessors from ARM Ltd.The purpose of this manual is to give the reader a good understanding of real-time system design in general, and the different mechanisms in OSE in particular.This manual is intended for users not familiar with real-time programming as well as experienced users and is intended for application developers.This manual describes how to use the ARM Kernel in the following sections:
• “Introduction to OSE” on page 9 gives an introduction into OSE and describes its main features.
• “Getting Started” on page 25 is a step by step tutorial on how to generate a system.
• “Configuring OSE Epsilon for ARM” on page 43 describes how to configure a system.
• “Building a System” on page 77 explains how to build and to generate OSE for ARM system.
• “System Design” on page 81 explains how to design an OSE for ARM system.
• “Illuminator Debugger” on page 111 gives an introduction in the OSE Illuminator system level debugger.
• “Timeout Server” on page 117 contains information about the OSE for ARM Time Out Server.
• “Glossary” on page 121 defines common terminology used with OSE
AR
M K
erne
l
8 • Introduction User’s Guide / 4.6
AR
M K
erne
l
User’s Guide / 4.6 Introduction to OSE • 9
2
2
2 Introduction to OSEOSE is a fast, compact, real-time operating system (RTOS) for microprocessors and microcontrollers for embedded systems.A system under OSE consists of a number of independent subprograms called processes. A process may be written to some extent as if it had the entire CPU for its own exclusive use.By assigning a priority to each process, OSE ensures that the right process is always executing. An event which requires another process with a higher priority to execute, forces an immediate switch of process. This scheme ensures fast response to important events. Processes co-operate by exchanging signals. A process may send a signal to the mailbox of another process to inform the receiver of an event or to respond to an event. Signal transmissions often cause execution to switch to another process (a task switch).A signal is a dynamically allocated message buffer containing a signal number and an optional data structure.Signal numbers are used to select which signals to receive, while leaving others in the mailbox of the receiving process. It is possible to ignore events which are unimportant at the moment simply by selecting which signals to receive. Other processes use the CPU while a process is waiting for a signal to arrive. Unused message buffers are stored in the central buffer pool until allocated by a process. Only one process at a time may access a signal (or message buffer), thereby eliminating conflicts.If a process needs to suspend execution for a specific interval of time, it calls OSE which monitors time and activates other processes during the wait.For more information on the OSE real-time operating system, see:
• “Definition of an RTOS” on page 10
• “Purpose of an RTOS” on page 10
• “Real-Time Operating System Tasks” on page 10
• “OSE Design Benefits” on page 12
• “Concurrent Processes” on page 12
• “Process Categories in OSE” on page 16
• “Process Types in OSE” on page 16
• “OSE Operating System Tools” on page 19
• “Fast Semaphores” on page 22
• “Semaphores” on page 23
AR
M K
erne
l
10 • Definition of an RTOS User’s Guide / 4.6
2.1 Definition of an RTOSAnyone is free to define the term real-time operating system and many have indeed done so. The following definition is often used:"A real-time operating system is a program that must respond to external events within a limited time."When a PC user is waiting for the result of a compilation, no disaster will occur if he must wait a few seconds more or less. On the other hand, 10 extra seconds in an aircraft control system may literally be the difference between life and death.A real-time operating system would certainly be useful in a personal computer, but it is a necessity in many embedded systems.
2.2 Purpose of an RTOSIt is important to note that a real-time operating system is designed to do the work that is done in almost every real-time system. It is intended to replace the control loops, jumps, calls and global variables that would otherwise control program execution.One major advantage of using a real-time operating system is that the manpower required to write a program system is substantially reduced. There are several reasons for this. One is that a large and potentially difficult part of the program has already been written and debugged before a project is even started.Another reason is that many small independent programs are considerably easier to write, debug and modify than one large complex program.Once a program system is written, it can be easier to debug when a real-time operating system is used if the debugging tools are designed to detect real-time problems in the interaction between many programs.The control structure of program systems without OS tends to vary considerably depending on both the application and the particular designer. Using an OS, the tools and techniques are the same in every project, making it much easier for programmers to be efficient in various projects.
2.3 Real-Time Operating System TasksA real-time operating system can do many things, some closer to the operating system core, some closer to the application. The following sections describe the basic tasks that comprise the core in most designs:
• “Resource Management” on page 11
• “Time Management” on page 11
• “Interprocess Communication” on page 11
• “Speed Considerations” on page 12
AR
M K
erne
l
User’s Guide / 4.6 Resource Management • 11
2
2
2.3.1 Resource ManagementThere are many resources in a real-time system, mainly the CPU, memory and various hardware such as ports, displays, communication links, etc.The user of a real-time OS must partition his program system into a number of program parts which may operate independently of each other. Such parts are called processes.Only one process can use the CPU at a time. It is an important task of the operating system to control activation of the various processes.Under the control of the operating system, many processes can share the same memory.The operating system also decides which process is to be granted use of the various other resources of the real-time system.
2.3.2 Time ManagementThere are often many timing requirements in a real-time system. Perhaps the operator has to be notified after a certain time, or a valve is to be open for a number of milliseconds.Most real-time operating systems have a notion of time and can schedule activities after a specified period or at a specified time.
2.3.3 Interprocess CommunicationWhen partitioning a real-time system into processes, the designer tries to keep them as isolated as possible. Ideally, there should be no ties between processes.Interprocess ties can appear in many forms: Global variables, subroutine calls, timing relationships, priority relationships, interrupt disables, semaphores, messages, etc.In this manual, any interaction between processes will be referred to as "interprocess communication", regardless of the actual form used.Unfortunately, it is often necessary to have communication between processes. Imagine, for example, the keyboard process and the screen process in a terminal. It is obvious they cannot be completely isolated from each other. One mark of a good system design, however, is that processes have few ties to each other.An important task of real-time operating systems is to handle communication between processes.Interprocess communication is channelled through the operating system for the following reasons:
• To keep inter process connections as few as possible.
• To make inter process connections clearly visible.
• To use standardized inter process connections.
• To allow debugging to focus on the interaction between processes.
• To improve process response time.
AR
M K
erne
l
12 • Speed Considerations User’s Guide / 4.6
2.3.4 Speed ConsiderationsGenerally, if a system is not fast enough with a real-time operating system, it will certainly not be fast enough without one. There are two reasons for this:
1. Systems running under a real-time operating system are always executing at the code section that is most important at any particular moment.
2. The task of directing the work must be done, either by the operating system or by the user code.
Intense competition between operating system manufacturers has produced some designs with very high performance. For those who plan to make their own kernel, it is possible, but not easy, to do better in a reasonably short time.
2.4 OSE Design BenefitsOne major advantage of using OSE is that the manpower required to write a program system is substantially reduced. There are several reasons for this. One is that a large and potentially difficult part of the program is already written and debugged even before a project is started. Another reason is that many small independent programs are considerably easier to write, debug and modify than is one large and complex program. Once a program system is written, it is simpler to debug when OSE is used, since the debugging tools are specifically designed to detect real-time problems in the interaction between many programs.You need not be an operating systems expert to write programs under OSE. The system calls are few and easy to understand and use. Extensive error-checking will reveal and pinpoint most mistakes, both when generating a system and when running it.Since every programmer uses the same limited set of tools, it is easier to understand, correct or modify programs written by others. Programs are rendered considerably more portable because the interface between modules is completely defined by the system calls. Most real-time high level description and specification languages tie in directly with OSE.OSE can be tailored to a specific application when configuring the operating system. If, in another project, you decide on another configuration, all modules written for the old configuration are completely compatible in the new system.OSE Systems also markets operating systems for other processors. The internals of each operating system is optimized for its particular processor. The user interfaces of all operating systems contain identical basic elements
2.5 Concurrent ProcessesA process is an independent program running under OSE.At every instant of time, the most important process ready to run is running. As soon as a more important process is ready to run, the current process is removed from the CPU and the new process is entered and allowed to run. This is called a process switch.The part of the operating system that performs process switches is often referred to as the dispatcher.
AR
M K
erne
l
User’s Guide / 4.6 Process States • 13
2
2
If you are running a system without a real-time operating system, the processor will often find itself unable to respond quickly to an event if the wrong part of the program is running and continues to do so for some time.Herein lies an important distinction between an OSE real-time operating systems and other operating systems.The OSE real-time operating system has what is referred to as a "pre-emptive" dispatcher. This means that the dispatcher has the power to stop the current process after the next assembler instruction and immediately move execution to a completely different part of the program system.All OSE operating systems have pre-emptive dispatchers and can be pre-empted even inside system calls.
2.5.1 Process StatesIn OSE, processes can have one of the following states:
• RUNNING
The process is the one currently in control of the CPU. In a single processor system, only one process can be in this state at a time.
• READY
The process needs the CPU and will be running as soon as it is permitted to do so. However, another process of higher or equal priority is RUNNING and the READY process must wait until all READY processes of higher priority are WAITING.
• WAITING
The process is waiting for something, for example a message, and has no need of the CPU.
Figure 2.1 Process states in OSE
AR
M K
erne
l
14 • Priority Based Process Scheduling User’s Guide / 4.6
2.5.2 Priority Based Process SchedulingSome operating system designs permit many processes to have the same priority. Different system designs have different methods for selecting which process to run when more than one process is READY on the same priority level. Some systems always select the oldest (created first) process first, whereas others select processes in some random fashion to give truly equal priority to the processes on the same priority level.The difference between processes on the same priority level and on different priority levels is that there is no process switch if a process on the same priority level becomes READY. If, on the other hand, a process on a higher priority level becomes ready, it will immediately become RUNNING and the previously running process becomes READY.This process scheduling principle will be referred to as priority based in this manual. Processes scheduled with this principle are called prioritized processes in an OSE system.
2.5.3 Round-Robin Process SchedulingIn priority based scheduling, processes are switched whenever a process on a higher priority level becomes READY. On the other hand, a process could run indefinitely if no process of higher priority became ready. That means that a process running indefinitely would lock out other processes.Another scheduling scheme is the round-robin principle. In this case, processes on the same priority level share CPU time, and they share it equally in the simplest case.When a process has used up its time-slice, it is interrupted by the operating system, even if the process is still RUNNING and may be put last in the queue. The size of time-slices need not be equal.The round-robin scheduling principle is used in many larger systems such as the UNIX operating systems. In such systems, the size of the time-slice is often changed at run-time according to various principles. Since round-robin is the only scheduling principle in many larger systems, response times are slow, for no process change occurs until the current time-slice is used up. Many unimportant processes may also be allocated CPU time before an important process.Many real-time operating systems allow the user to select either a priority based or a round-robin scheduling scheme. Some of them allow both principles to be used at the same time in one system.A system using both principles simultaneously might be utilized in the following way:
1. Time critical processes are scheduled on a priority basis and thus allowed to finish their job without interruption.
2. Operators are round-robin scheduled on one priority level. Operators have time- slices of equal length, except the superuser who has a longer time-slice. Operators thus share
AR
M K
erne
l
User’s Guide / 4.6 Round-Robin Process Scheduling • 15
2
2
the available CPU time equally. The superuser is allowed a larger share of CPU resources. None of the operators can lock the others out from the system.
3. Tests and other housekeeping processes share time on a lower priority level. They are allowed CPU time only when nothing time critical is under way and no operator has work to do.
Processes intended for a priority based scheduling scheme must be written in a different way than those intended for round-robin scheduling. There must be no infinite loops in the internal control structure in a process written for priority based scheduling.If there is an infinite loop in one process, processes on lower priorities will never be allowed to use the CPU. If the loop contains a call to the operating system that causes the process to become WAITING, lower priority processes can come in, and there is no problem. Processes written for round-robin scheduling can contain whatever loops the programmer desires; in this respect they are always handled safely by the operating system.In an OSE system, processes scheduled according to the round-robin principle are called background processes.
For each priority equal or below the background priority level, a process (FIFO) queue is maintained. Processes enter the READY list at the end of the queue and processes are selected for execution from the head of the queue. OSE gives each process a user selected time-slice for running before pre-empting it to allow the next process in the READY queue to run.
Figure 2.2 Round-robin process scheduling
Background processeswith equal priority
Runningprocess
CPU
Waiting background processeswhich become ready
AR
M K
erne
l
16 • Process Categories in OSE User’s Guide / 4.6
2.6 Process Categories in OSEProcesses can be divided into two types depending on whether they always exist or are created and killed as they are needed. Static processes always exist, whereas dynamic processes may be created and killed at run-time.In the most commonly used design with static processes, one process starts executing after system start, normally the highest prioritized, and all static processes have already been created and are READY.It is an error for a static process to kill itself, and it is an error for a process to try to kill a static process. This ensures that a static process always exists, and it is thus always possible to communicate with a static process. The real-time operating system can declare the names of all static processes' public. Any process may then declare the name of a static process external and can obtain its process ID and communicate with it.
2.7 Process Types in OSEProcess types in OSE are described in:
• “Prioritized Processes” on page 17
• “Background Processes” on page 17
• “Interrupt Processes” on page 17
• “Interrupt Performance” on page 18
• “Timer Interrupt Processes” on page 19
AR
M K
erne
l
User’s Guide / 4.6 Prioritized Processes • 17
2
2
2.7.1 Prioritized ProcessesPrioritized processes are the most common processes in a typical OSE system.Prioritized processes have a strict order of priority. The highest priority process will always run before every other process. The lowest priority process will be allowed to run only when no other prioritized process is ready. If two processes are assigned the same priority, the choice of precedence between the two processes is made by OSE.When a process has no further work to do for the moment, it becomes not ready. A process is not ready when it is waiting for a message or when it is waiting for a delay to end or when it is waiting at a semaphore. A process is swapped out from the CPU when it becomes not ready or when a process of higher priority becomes ready. Note that a process may be interrupted between almost any two assembler instructions and in the middle of any C instruction.A process is swapped in if all processes of higher priority are not ready and the process itself is or becomes ready.
2.7.2 Background ProcessesThese are identical to prioritized processes except that they do not have priority. A background process will only be allowed to run when no prioritized process is ready. The time left over when no prioritized process is running is divided between ready background processes. Running background process is switched by the operating system at user defined intervals.A background process is allowed to execute until it becomes not ready or a prioritized process becomes ready or until the background process has executed for the duration of the user defined interval. Background processes may be written either in assembly or C.
2.7.3 Interrupt ProcessesAn interrupt is a hardware generated event that will cause the CPU to suspend the currently running process and turn control over to the interrupt routine dedicated to that particular interrupt. Interrupts are used in systems with and without real-time operating system.The programs handling interrupts are called processes in some operating systems, service routines in others and device drivers or part of device drivers in still other systems. In OSE they are called interrupt processes. Some real-time operating systems canalize all interrupts through the operating system that then calls the appropriate interrupt process. Others let the user write the calling code and then provide entry and exit calls for the process. In some cases the entry call can be avoided.The latter principle offers faster interrupt handling but less convenience. An important performance advantage of the latter method is that interrupts which do not need use of the operating system can avoid both the entry and the exit routine. An interrupt process is called whenever its interrupt occurs, provided that no other interrupt of higher or equal hardware priority is running. Should such be the case, this interrupt must wait its turn.
AR
M K
erne
l
18 • Interrupt Performance User’s Guide / 4.6
Processes have priorities assigned by the operating system. Interrupt processes have the priority assigned to its interrupt by hardware. In some CPUs they may, however, change priority by writing to some status register.
There can exist only one interrupt process for each of the available hardware interrupt vectors. An interrupt process is called as a subroutine whenever its interrupt occurs, provided that no other interrupt is running.
2.7.4 Interrupt PerformanceInterrupt response time is the time elapsed between the occurrence of an interrupt and the execution of the first instruction of the interrupt process.Most operating systems and many user programs disable interrupts from time to time. The longest time in which interrupts are disabled is called interrupt latency. Interrupt latency of a real-time operating system is one of the most important performance factors. It is often difficult to design a system when interrupt latency is not known.Real-time operating systems vary considerably with regard to the calls they allow to be made from an interrupt process. Some permit all calls (with the exception of those which cause the caller to sleep). Others, however, permit only a single call from interrupt
Figure 2.3 Interrupt processes
Hardware Delay
EncodingIncomingInterrupt
Stacking ofCPU’s statedata
Finish currentInstruction
Operating systemor user codefinishes executionof longest criticalsection
Interrupt processincluding systemcalls
Operating systemfinishes interruptservicing
Operating systemcontext switchUSER
PROCESSOSE
Hardware
Software
External Interrupt
AR
M K
erne
l
User’s Guide / 4.6 Timer Interrupt Processes • 19
2
2
processes. This design is used by operating systems that do not disable interrupts. Another way to effectively achieve zero interrupt latency is to disable interrupts for a shorter time than the longest CPU instruction. This method has the advantage of permitting most system calls to be used by an interrupt process.Many real-time operating systems allow the user to set aside some hardware interrupt priority levels and request that these levels should not be disabled by a real-time operating system. Interrupt handlers working on such levels may never call any real-time operating system function. If they do so nonetheless, the system will crash sooner or later. Since such interrupts cannot use system calls, they are, among other things, unable to activate a process that runs under non-interrupt. If other processes are to act on data from such an interrupt, they must poll some suitable variables.
2.7.5 Timer Interrupt ProcessesTimer interrupt processes work like interrupt processes except for the manner in which they are called. For each timer interrupt process the user selects a number of system ticks to elapse between each call to the process.
2.8 OSE Operating System ToolsThere are hundreds of slightly different operating system tools available. As it is outside the scope of this short introduction to describe them all, only one type of tool will be described in detail; messages as used under OSE. A few more of the most common tools will be described in terms of their differences.The user partitions his system into processes that are then activated as appropriate by the real-time operating system. When these processes need to communicate with each other or otherwise affect one another, services are requested from the operating system through the use of system calls.A system call is not different from any procedure call except for one thing: a process making a system call can be put to sleep by the operating system.This is the one thing that makes system calls similar. They may either implicitly request that the caller becomes WAITING, or they may make a higher priority process READY. In the latter case the effect is similar; the caller becomes READY while the other process becomes RUNNING, effectively putting the caller to sleep. In some situations, control is returned to the caller, which may then continue execution.The above implies that any of these tools can be used to emulate any of the others.
Why are there so many tools? One reason is that once the basic "go-to-sleep"- mechanism is built, it is relatively simple to add many tools. Apart from this, when a tool is accurately and wisely used in the situation for which it has been designed, additional convenience or sometimes higher performance can be obtained.See also:
• “Messages” on page 20
• “Fast Semaphores” on page 22
• “Semaphores” on page 23
AR
M K
erne
l
20 • Messages User’s Guide / 4.6
2.8.1 MessagesWhen a process wants to receive a message it calls the operating system, requesting a message. If none is available, the operating system puts the process to sleep until one arrives.When a process wants to send a message, it calls the operating system, submitting the message. If the receiving process is of higher priority, or if a higher priority process is sleeping at the mailbox in question, the calling process is put to sleep, and the higher priority process is allowed to use the CPU. Mailboxes are described further in this chapter.A message is often actually a buffer, an area of memory, where processes may read and write data. A buffer may be used by many different processes, but only one process at a time may access a buffer. If processes should access buffers without control, the resulting errors would be difficult to find. Messages not only carry data; they may also initiate actions by the various processes.
2.8.1.1 Message Passing Through Mailboxes
OSE is not using message passing trough mailboxes. Under some other operating systems, messages are sent to mailboxes to which any process can send and from which any process can receive. In this case there must be some set of rules determining which processes are to send to a certain mailbox and which processes are to receive from the mailbox.Processes must send their messages to the mailbox where the addressee is waiting when it requires these messages. Which mailbox to send to is determined by set of rules that evolves as the system is designed and tested. If some messages are unwanted at certain times, more mailboxes can be created and processes can wait at these.If it is not desirable to create more mailboxes, the user may design his process as a state machine and receive all messages at one mailbox. When a new message is added to the work of the process, the number of states can double. Most of the state machine is often affected when new functions are added to it.Processes must be carefully designed, since a process that needs prompt response from another must know at which mailbox the target process is waiting or else it must send messages to all possible mailboxes. In the latter case, the unused messages must be removed once the process has received one copy of the message. Mailboxes are not used in the OSE operating system.
AR
M K
erne
l
User’s Guide / 4.6 Messages • 21
2
2
The figure below shows mailbox message passing in one direction only. In reality, the situation becomes more complex when messages are passed in both directions.
2.8.1.2 Direct Message Passing in OSE
OSE operating systems send messages directly to processes. In OSE the name signal is also often used. Messages and Signals are exactly the same in an OSE system. In this scheme it is not necessary to know which mailboxes to create, kill and send to and receive from. With this design it is not possible to avoid unwanted messages by creating more mailboxes. Possibly, more processes could be introduced to solve the problem.
Figure 2.4 Mailbox message passing
Sending Processes Receiving Processes
AR
M K
erne
l
22 • Fast Semaphores User’s Guide / 4.6
Another solution is to let a process select the messages it is interested in receiving at any particular moment. If this tool is available, the "prompt response" problem of the previous paragraph is also solved, for a process is always waiting at the same mailbox.
In OSE signals (or messages) are sent between processes. Each message is a buffer, an area of memory, where processes may read and write data. A buffer may be used by many different processes, but only one process at a time may access a buffer. Signals not only carry data, they also initiate actions by the various processes.All processes can exchange signals, even those residing in other computers. (Through the use of a link handler.)When a process gains access to a signal buffer by allocating it or receiving it, the process becomes the owner of the buffer. Only the owner may perform operations on the buffer.Once a signal has been sent to another process it can no longer be accessed by the sending process. A process may select the signals it is interested in receiving at any particular moment. The process will then wait for signals to arrive. Meanwhile, other processes are allowed to execute.
2.8.2 Fast SemaphoresFast semaphores is a specific OSE feature and are intended for those rare cases where user programs cannot use message passing due to timing problems. For example, a fast semaphore may be used to count characters in a user implemented buffer between an interrupt process receiving characters and a prioritized process consuming characters.
Figure 2.5 Direct message passing
Sending Processes Receiving Processes
AR
M K
erne
l
User’s Guide / 4.6 Semaphores • 23
2
2
Fast semaphores work like this: A fast semaphore is a signed integer owned by a process. It is operated by system calls WAIT (WAIT_FSEM) and SIGNAL (SIGNAL_FSEM). Only the owner may wait at a fast semaphore. Other processes may signal it.
2.8.3 SemaphoresSemaphores are somewhat similar to fast semaphores, but they differ in one very important aspect:A semaphore is not related to any specific process. Any background or prioritized process may wait at a semaphore, not just the owner. Any type of process may signal a semaphore.The main purpose of semaphores is to protect critical code sections from concurrent execution (so called mutual exclusion) without disabling interrupts. This is often done to protect global shared resources. If the compiler supports static initialisation of C structures this can be used to declare a semaphore at compile time.OSE is a message-passing real-time operating system. It is therefore strongly recommended to not use global variables and semaphores in an OSE system. Only message passing design ensures a clear and secure system and makes it possible to use some powerful features in the OSE Illuminator system level debugger. Semaphores are mainly used to ensure that only one process at a time is using a global shared resource. As soon as the process currently occupying the resource releases it, it will automatically be given to the next in its waiting queue. Use the wait_sem system call to get in line to use the resource as soon as possible and the signal_sem system call to releases it as soon as the resource is no longer needed.A semaphore is a counter to which 1 can be added and from which 1 can be subtracted. Adding 1 is called "signalling the semaphore" and subtracting 1 is called "waiting for the semaphore". If the counter is 0 and a process tries to subtract 1, the subtracting (waiting) process is put to sleep.If a process is asleep at the semaphore and another process signals the semaphore, the sleeping process becomes READY and will be allowed to run if it is of higher priority than the signalling process. The counter of a semaphore may be a single bit, in which case the semaphore is referred to as a binary semaphore. The other type is often called a counting semaphore.
AR
M K
erne
l
24 • Semaphores User’s Guide / 4.6
Semaphore example:Assume a system with two printers. When the system is started, the semaphore is initialised to 2. Each process needing a printer first waits at the semaphore. When the process has finished with the printer, it signals the semaphore. When the first two processes wait for the semaphore, the counter is simply decreased. When the third process waits for the semaphore, it is put to sleep because the semaphore is 0. When one of the first two processes is finished, the semaphore is signalled and the third process is awakened. In this way, the semaphore sees to it that only one process at a time uses each printer.One way to solve the same problem with messages: A process owns the printer (the printer process for example). Processes that need a printer send a message to the printer process, and when the process receives a reply message, the printer is available. As long as there is no reply message, the requesting process is sleeping.
AR
M K
erne
l
User’s Guide / 4.6 Getting Started • 25
2
2
3 Getting StartedThis is a step-by-step tutorial that shows how to generate a simple application with the OSE for ARM real-time operating system, see “Example System Description” on page 26. You will be guided through the configuration and the generation of an example system in “Step by Step Tutorial” on page 28.
AR
M K
erne
l
26 • Example System Description User’s Guide / 4.6
3.1 Example System DescriptionIn this example we have designed a small motor controller system which is working completely inside the processor without using any peripheral functions. You can find the source files in the example-directory of the OSE delivery. The following figure shows the example system:
There is a keyboard where commands can be typed, a test process which reads some current sensor, a display process where messages can be displayed, a motor process controlling the rather big motor and a control process controlling the system. There is also a runner process, which gives simulated input to the keyboard and the test process.
Figure 3.1 Example system
runner
keyhandtest
control
motor display
MOTOR_ON
OVERCURR
CHARACTER
KEY_R
KEY
CURRENT
KEY_HIT
TEST_VAL
bg1 bg2
AR
M K
erne
l
User’s Guide / 4.6 Example System Description • 27
2
2
There are eight signals used:• KEY_HIT• KEY• KEY_R• MOTORON• CURRENT• OVERCURR• CHARACTER• TEST_VAL
The system consists of seven source files:• runner.c
This process gives test stimuli (signals KEY_HIT and TEST_VAL) to the keyhand and test processes. This process calls also the function feedback() at a regular rate. Feedback is included in the module led.c and controls the LEDs on the evaluation board (if there are LEDs available on the board).
• keyhand.cIn reality an interrupt process managing the keyboard. In this simulated system this process receives the signal KEY_HIT from runner. The characters are just echoed to control, and keyhand then waits for a receipt (signal KEY_R).
• test.cIn reality a timer-interrupt process, measuring the current from a sensor and sending the value to control. In this simulated system test receives TEST_VAL signals from runner, and transfers the content inside the signal CURRENT to control.
• motor.cThis process receives the MOTORON signal and starts and stops the motor accordingly.
• display.cIf a character is displayable, control will forward it to display.
• control.cThis is the spider in the net, controlling the system. Receives KEY_HIT and CURRENT signals, sends MOTORON to motor, CHARACTER and OVERCURR to display, and KEY_R to keyhand.
• bg.cTwo background processes, which do not have a specific functionality. It is just to show how to setup a background process.
• led.cIncludes the function feedback() which controls a row of led’s on the evaluation board.
AR
M K
erne
l
28 • Step by Step Tutorial User’s Guide / 4.6
3.2 Step by Step TutorialThis tutorial shows you how to generate the example system in the following sections:
• “Equipment” on page 29
• “Preparation” on page 30
• “OSE Configuration” on page 30
• “Getting the System Files” on page 33
• “Getting Specific Drivers” on page 33
• “Getting the Example Source Files” on page 34
• “Building the System with ARM ADS” on page 35
• “Building the System with IAR EWB” on page 36
• “Building the System with GNU GCC” on page 37
• “Running the System without OSE Illuminator” on page 40
• “Running the System with OSE Illuminator” on page 40
• “Debugging” on page 42
AR
M K
erne
l
User’s Guide / 4.6 Equipment • 29
2
2
3.2.1 EquipmentTo run this Getting Started System, you need the following equipment:
• PC running Windows 98, 2000 or NT.
• A target evaluation board preferably one where an OSE for ARM board support package is delivered. This tutorial is designed for the ARM Evaluator-7T evaluation board. You could use any board with a processor where the OSE for ARM kernel runs but you might have to modify the system startup files and some drivers.
• Your preferred debugger connected to your selected ARM evaluation board.
• One of the following development environments:
• ARM Developer Suite• IAR Embedded Workbench• GNU GCC
• OSE Epsilon for ARM RTOS.
• If you would like to run also the OSE Illuminator system level debugger, you will need the additional equipment:
• A serial line connected of one of your PC’s COM ports to the serial port of your target board which is supported by the serial device driver.
• OSE Illuminator which is delivered on a separate CD. Please consult the OSE Illuminator User’s Guide for information about installation and usage.
AR
M K
erne
l
30 • Preparation User’s Guide / 4.6
3.2.2 PreparationThis Getting Started example is not a ready to run “plug-and-play” project where you push a button and your system is generated and after down loading you see something running in the target.This is maybe quite nice for a demonstration but not very useful to learn how to configure and generate an OSE for ARM system. In this Tutorial we will guide you through the whole configuration and generation process. You will learn what files you need and which configuration entries you have to define.First, you will need to create a work directory in a suitable place.
3.2.3 OSE ConfigurationThe OSE operating system can be configured to have completely different characteristics depending on the trade-off you want to make between speed, memory consumption and code size. The configuration is accomplished by entering the desired values into the osarm.con configuration file.
1. Copy the osarm.con configuration file into your working directory. You will find this file at:
<installdir>\arm\krnxxx\<yourCompiler>\conf\
Be sure to copy osarm.com from the directory corresponding to your used compiler.
2. Start your preferred editor and load osarm.con into the editor.
3. Check the compiler configuration line. It should fit your used compiler environment (ARM for ARM ADS, IAR for IAR Systems and GNU for GNU GCC. The option SINGLECHIP is not used in this example.
4. Define a target name such as:
TARGET_NAME motcon
5. For the ARM Evaluator-7T evaluation board define the following CPU:
CPU ARM7T DMI
6. Define the memory endianess model such as:
MEMORY_MODEL LITTLE
7.We will enable some kernel internal debug functions:
DEBUG YESBUFFER_CHECK YESSTACK_CHECK YES
AR
M K
erne
l
User’s Guide / 4.6 OSE Configuration • 31
2
2
8.If you will not use the OSE Illuminator system level debugger enter the following debugger options:
OPTION DEBUGGER,NO
If you are using the OSE Illuminator system level debugger over a serial line enter the following debugger option definitions:
OPTION DEBUGGER,ONCHIP,1024,20
This will generate the OSE for ARM debug kernel. Please consult “Option Debugger” on page 52 for more information concerning the debugger options.
It is simpler to first generate a system without OSE Illuminator support.
9. You do not need to modify the memory allocation default settings for this simple getting started example:
POOL 1024BUFFERSIZES 4,8,16,32,64,128,256,512
This will define a message pool of a size of 1024 bytes and individual message sizes of 4, 8, 16, 32, 64, 128, 256 and 512 bytes.
10.We will use the default interrupt and temporary stack sizes:
ISTACK_SIZE 256,512TEMP_STACK_SIZE 256
11.We define one start handler. This handler is included in the file timer_setup.* of the board support package delivery.
START_HANDLER TimerSetup
12.Now we are defining the prioritized processes:
PRI_PROC motor,256,14PRI_PROC control,256,17PRI_PROC test,256,17PRI_PROC display,256,17PRI_PROC keyhand,256,17PRI_PROC runner,256,18
For all process we declare a stack of 256 bytes. All processes have the same priority of 17 except process “runner” which has a priority of 18 and motor with 14.
13.To show how OSE background processes are defined, we have included the background processes bg1 and bg2:
BG_PROC bg1,256,10BG_PROC bg2,256,10
The two background processes have a stack of 256 bytes and a times slice of 10 ticks.
AR
M K
erne
l
32 • OSE Configuration User’s Guide / 4.6
14.The file osarm.con is now complete and should look more or less like this (without comments):
COMPILER ARMTARGET_NAME motconCPU ARM7T DMIMEMORY_MODEL LITTLEDEBUG YESBUFFER_CHECK YESSTACK_CHECK YESOPTION DEBUGGER,ONCHIP,1024,20POOL 1024BUFFERSIZES 4,8,16,32,64,128,256,512ISTACK_SIZE 256,512TEMP_STACK_SIZE 256START_HANDLER TimerSetupPRI_PROC motor,256,14PRI_PROC control,256,17PRI_PROC test,256,17PRI_PROC display,256,17PRI_PROC keyhand,256,17PRI_PROC runner,256,18BG_PROC bg1,256,10BG_PROC bg2,256,10END
The file can vary depending on used compiler, evaluation board and debug option.
15.Open a shell window and change the directory to your example working directory. Run the configuration utility confarm.exe by declaring osarm.con as input file:
<install_dir>\arm\krnxxx\bin\confarmosarm.con
For every change in the osarm.con configuration file the confarm.exe utility must be executed again.
If your IDE allows to define external utilities or you are using a makefile you could add this step in the IDE or in the makefile.
16.The kernel will be generated in your working directory. The file name of the kernel is osarm.*. The extension differs from compiler to compiler (ARM: osarm.s, GNU: osarm.S, IAR: osarm.s79).
AR
M K
erne
l
User’s Guide / 4.6 Getting the System Files • 33
2
2
3.2.4 Getting the System Files1. We will copy and assemble the OSE for ARM system files which are needed to setup
and start the system.
2. To setup the C system you will need the C startup file. Copy the file crt0.* into your working directory. You will find this file in the OSE for ARM board support package of your selected board (ARM Evaluator-7T board in this example):
<installdir>\arm\bspxxx\Evaluator7T\<yourCompiler>\src\
The file extension differs from compiler to compiler (ARM: crt0.s, GNU: crt0.S, IAR: crt0.s79).
3. OSE for ARM needs an interrupt handler to manage all interrupts. Copy the file inthdlr.* into your working directory. You will find this file in the OSE for ARM board support package of your selected board (ARM Evaluator-7T board in this example):
<installdir>\arm\bspxxx\Evaluator7T\<yourCompiler>\src\
The file extension differs from compiler to compiler (ARM: inthdlr.s, GNU: inthdlr.S, IAR: inthdlr.s79).
4. The OSE-Tick-Timer needs to be initialized before OSE is started. Copy the file timer_setup.* into your working directory. You will find this file in the OSE for ARM board support package of your selected board (ARM Evaluator-7T board in this example):
<installdir>\arm\bspxxx\Evaluator7T\<yourCompiler>\src\
The file extension differs from compiler to compiler (ARM: timer_setup.s, GNU: timer_setup.S, IAR: timer_setup.s79).
3.2.5 Getting Specific Drivers1. If you want to use the OSE Illuminator system level debugger and have therefore set
OPTION DEBUGGER,ONCHIP,1024,20, you also need a serial driver to connect Illuminator to your target board.
If you are using the ARM environment and the ARM Evaluator-7T board copy the file eldm_uart.* into your working directory.
You will find this file in the OSE for ARM board support package of your selected board (ARM Evaluator-7T board in this example):
<installdir>\arm\bspxxx\<yourBoard><yourCompiler>\src\
The file extension differs from compiler to compiler (ARM: eldm_uart.s, GNU: eldm_uart.S, IAR: eldm_uart.s79).
AR
M K
erne
l
34 • Getting the Example Source Files User’s Guide / 4.6
3.2.6 Getting the Example Source Files1. Every process of the example system resides in one C file. Copy all example *.c files
into your working directory. You will find these files in the example directory of the kernel delivery:
<installdir>\arm\krnxxx\<yourCompiler>\exp\motcon\
The following files will be copied: motor.c, control.c, test.c, display.c, keyhand.c, runner.c, and bg.c.
2. Every signal (or message) of the example system resides in one signal file. These signals will be included by the processes. Copy all example *.sig files into your working directory. You will find these files in the example directory of the kernel delivery:
<installdir>\arm\krnxxx\<yourCompiler>\exp\motcon\
The following files will be copied: • characte.sig
• current.sig • key.sig
• key_hit.sig
• key_r.sig • motoron.sig
• overcurr.sig
• test_val.sig
3. There is a system header file delivered for the example. This file will be included by some processes. Copy the file system2.h into your working directory. You will find this file in the example directory of the kernel delivery:
<installdir>\arm\krnxxx\<yourCompiler>\exp\motcon\
4. If there are LEDs on your board available there is a function called feedback() to manage these LEDs. This function is defined in the file led.c and led.h. Copy led.c and led.h to your working directory. You will find these files in the board support package directory for your selected board, e.g.:
<installdir>\arm\bspxxx\<yourBoard>\src\
<installdir>\arm\bspxxx\<yourBoard>\include\
AR
M K
erne
l
User’s Guide / 4.6 Building the System with ARM ADS • 35
2
2
3.2.7 Building the System with ARM ADS1.We will build the system with the ARM ADS development environment. If you are
using the IAR environment, skip this chapter and go to “Building the System with IAR EWB” on page 36. If you are using the GNU environment, skip this chapter and go to “Building the System with GNU GCC” on page 37 .
2.Start the ARM ADS development environment.
3.Menu File -> New -> Thumb Executable ImageSelect Project Name (e.g. motcon) and choose a Location.
4.Change the project settings:Menu Edit -> DebugRel settings...Select pane Access Path -> System PathsAdd the following paths:
<installdir>\arm\krnxxx\ads\include<installdir>\arm\bspxxx\include<installdir>\arm\bspxxx\<yourBoard>\include<installdir>\arm\bspxxx\<yourBoard>\ads\include
Select pane Build extras and uncheck Use modification date caching.
Select pane ARM Assembler -> ATPCS.
Check ARM/Thumb interworking.
Select pane ARM Linker.
Choose Linktype: Scattered and enter a Scatterdefinition File.
Now click save.
5. Adding files to the project:
Menu Project -> Add Files => File selector dialogue.
a) Select all .c filesb) Select all .s files
6. Building the project
Menu Project -> Make
7.Go to “Running the System without OSE Illuminator” on page 40 or “Running the System with OSE Illuminator” on page 40.
AR
M K
erne
l
36 • Building the System with IAR EWB User’s Guide / 4.6
3.2.8 Building the System with IAR EWB1.We will build the system with the IAR Embedded Workbench development
environment. If you are using the ARM ADS development environment, skip this chapter and go to “Building the System with ARM ADS” on page 35. If you are using the GNU environment, skip this chapter and go to “Building the System with GNU GCC” on page 37.
2. Create a new project:Menu: File -> New -> ProjectGo to your working directory, enter a project name and press Create.
3. Add files to the project:
Menu: Project -> Files
a) Select C files:motor.c, control c, test.c, display.c, keyhand.c, runner.c, bg.c, led.c
b) Select assembler files:crt0.s79, inthdler.s79, timer_setup.s79osarm.s79(If you do not have this file, make sure to run confarm.exe in your working directory and that the compiler switch in osarm.con is set to IAR).eldm_uart.s79 (only if you plan to use illuminator).
4. Project settings
Select Debug in the project window and to the Menu Project -> Options
Select pane ICCARM -> Preprocessor.
Add the following paths (each in a separate line):
<installdir>\ARM\krnxxx\IAR\include<installdir>\ARM\bspxxx\include<installdir>\ARM\bspxxx\<your Board>include<installdir>\ARM\bspxxx\<your Board>IAR\include
Select pane AARM -> Include and add the above paths here as well.
Select pane XLINK -> IncludeSet Override Default and enter the path to an XCL file for your board.
Select pane XLINK -> DiagnosticsSet No global type checking to prevent warnings about union SIGNAL having more then one definition.
5. Building the project
Menu Project - > Make
6. Go to “Running the System without OSE Illuminator” on page 40 or “Running the System with OSE Illuminator” on page 40.
AR
M K
erne
l
User’s Guide / 4.6 Building the System with GNU GCC • 37
2
2
3.2.9 Building the System with GNU GCC1.We will use the GNU make utility to build the system with the GNU GCC compiler. If
you are using the ARM ADS development environment, skip this chapter and go to “Building the System with ARM ADS” on page 35. If you are using the IAR Embedded Workbench environment, skip this chapter and go to “Building the System with IAR EWB” on page 36.
2. Start your preferred editor and create a Makefile. The next steps will explain the makefile entries for the example project.
3. First we will define the compiler and assembler macros and a remove macro for the host operating system:
CC=arm-thumb-elf-gccAS=arm-thumb-elf-asLD=arm-thumb-elf-ldCPP=$(CC) -E -xc
RM=rm -f
4. Define the compiler assembler and linker flags:
ASFLAGS = -mthumb-interwork -EL CFLAGS = -Wall -O2 -fomit-frame-pointer CFLAGS+ = -mthumb -mthumb-interwork -mlittle-endianLDFLAGS = -s -marmelf -e OSE_RESET -T gnu.lnk
5. Define the OSE include path:
INC = -I<install_dir>/arm/krnxxx/gnu/include
6. Add the GNU include path:
INC += -I<gnu_install_dir>/arm-thumb-elf/include
7. Define the GNU library for the linking:
LIBS = -lc
8. Set the executable and build name:
all: motcon.elf
AR
M K
erne
l
38 • Building the System with GNU GCC User’s Guide / 4.6
9. Define all C-files and the related object macro:
C_SRC = bg.cC_SRC += control.cC_SRC += display.cC_SRC += keyhand.cC_SRC += motor.cC_SRC += runner.cC_SRC += test.cC_SRC += timer.c
C_OBJ = $(C_SRC:.c=.o)
10.Define all Assembler files and the related object macro:
AS_SRC = osarm.SAS_SRC += crt0.SAS_SRC += inthdlr.SAS_SRC += timer_setup.S
AS_OBJ = $(AS_SRC:.s=.o)
11.Set the makefile meta rules for assembling and linking:
OBJ= $(C_OBJ) $(AS_OBJ)
.SUFFIXES: .c .o.S
.S.o: $(CC) $(INC) $(CFLAGS) -c -o $@ $< .c.o: $(CC) $(CFLAGS) $(INC) -c $< -o $@
12.Instead of running the OSE for ARM configuration utility confarm.exe manually (see “OSE Configuration” on page 30), you could include this step in the makefile:
osarm.S : osarm.con confarm osarm.con
13.Define the linking process:
motcon.elf: $(OBJ) osarm.o gnu.lnk $(LD) $(LDFLAGS) -Map motcon.map $(OBJ) $(LIBS) \ osarm.o -o motcon.elf
14.You can also set a cleaning action:
clean:$(RM) osarm.S$(RM) *.o$(RM) *.elf$(RM) *.*~
AR
M K
erne
l
User’s Guide / 4.6 Building the System with GNU GCC • 39
2
2
15.The file Makefile is now complete and should look more or less like this:CC=arm-thumb-elf-gccAS=arm-thumb-elf-asLD=arm-thumb-elf-ldCPP=$(CC) -E -xc
# OS stuffRM=rm -f
ASFLAGS = -mthumb-interwork -EL CFLAGS = -Wall -O2 -fomit-frame-pointerCFLAGS = -mthumb -mthumb -interwork -mlittle-endian
LDFLAGS = -s -marmelf -e OSE_RESET -T gnu.lnkINC = -I/OSE/epsilon/ARM/krn361/GNU/includeINC += -I/usr/arm-thumb-elf/include
LIBS = -lc
all: motcon.elf
C_SRC = bg.cC_SRC += control.cC_SRC += display.cC_SRC += keyhand.cC_SRC += motor.cC_SRC += runner.cC_SRC += test.cC_SRC += timer.c
C_OBJ = $(C_SRC:.c=.o)
AS_SRC = osarm.SAS_SRC += crt0.SAS_SRC += inthdlr.SAS_SRC += timer_setup.SAS_OBJ = $(AS_SRC:.S=.o)OBJ= $(C_OBJ) $(AS_OBJ).SUFFIXES: .c .o .S.S.o:$(CC) $(CFLAGS) $(INC) -c $< -o [email protected]:$(CC) $(CFLAGS) $(INC) -c $< -o $@ osarm.S : osarm.conconfarm osarm.con
motcon.elf: $(OBJ) osarm.o gnu.lnk$(LD) $(LDFLAGS) -Map motcon.map $(OBJ) $(LIBS) osarm.o -o motcon.elf
clean:$(RM) osarm.S$(RM) *.o$(RM) *.elf$(RM) *.*~
The file can vary depending on used compiler, evaluation board and debug option.
16.Run the make utility to generate the executable.
17.Go to “Running the System without OSE Illuminator” on page 40 or “Running the System with OSE Illuminator” on page 40.
AR
M K
erne
l
40 • Running the System without OSE Illuminator User’s Guide / 4.6
3.2.10 Running the System without OSE IlluminatorIf you are running the system without our OSE Illuminator system level debugger, you just need to download the generated executable and test it. Connect your preferred source level debugger to the target system and start it. Setup the board to enable the memory system and download the generated executable. Set some breakpoints at different location inside the example system and check the function of the whole system.
3.2.11 Running the System with OSE IlluminatorIlluminator is a system level debugger for OSE real-time operating systems. In a typical real-time system, the crucial parts are the interfaces between the different system components and the real-time behaviour and status of system functions and resources. In an OSE system, the components are processes and the interface is always made up of OSE signals. With a traditional source code debugger it would be a tough job to supervise or debug these interfaces because a source level debugger concentrates on code lines. The OSE Illuminator system level debugger is designed to make it easy to work with the signal interfaces.The main system level debugger functionality resides in the target system for the serial line version. On the host, you have the graphical user interface (written in Java) and a communication module called Epsilon Debug Server (edbgserver). For the serial line Illuminator, you need a free serial interface in your target system and on your host. It is an easy to use and simple configurable architecture which is very well suited for single chip systems.If you have selected the debug option (OPTION DEBUGGER) in the ARM kernel configuration file, the Debug Kernel will be generated. The Debug Kernel includes beside the standard OSE for ARM kernel also debug code and memory to use with the OSE Illuminator system level debugger.To connect the Debug Kernel to the host system, you need a serial driver eldm_uart.s), the serial interfaces and the serial cable.
AR
M K
erne
l
User’s Guide / 4.6 Running the System with OSE Illuminator • 41
2
2
18.Connect your Source Level Debugger to the JTAG debug port of your evaluation board. Switch-on the debugger.
19.Connect the serial cable from a free serial port on your host PC to the serial interface connector of the target board.
20.Switch-on the target board.
21.Start the debugger and download the generated file motcon.* into your target system.
22.Run the target system from your source level debugger.
Figure 3.2 Serial line Illuminator system
Illuminator
edbgserver
OSE for ARM
serial.*
Serial Line
Host Target
comx uart
TCP/IP
Debug Kernel
AR
M K
erne
l
42 • Debugging User’s Guide / 4.6
3.2.12 DebuggingWe are supposing that you have generated the system for Serial Line Illuminator, downloaded the executable into your target system and started the target program.
3.2.12.1Epsilon Debug Server
You have to start the communication program on the host system called edbgserver manually.If you have installed OSE for ARM at the default location on your PC, you can find the edbgserver.exe file at the location:
c:\ose\epsilon\arm\krnxxx\bin
Open a MS-DOS shell window and change the working directory of this window to the directory where edbgserver.exe is located. Run edbgserver.exe.You will now see the following window:
3.2.12.2Debugging with OSE IlluminatorPlease consult the “Illuminator User’s Guide” for a detailed description of OSE Illuminator.
AR
M K
erne
l
User’s Guide / 4.6 Configuring OSE Epsilon for ARM • 43
2
2
4 Configuring OSE Epsilon for ARMThe configuration file osarm.con must be customized to your particular configuration. Edit this file until it meets system requirements. Always keep a copy of the original configuration file.Most declarations in the configuration file must be present at system generation. The order in which declarations appear is also fixed. If you encounter problems with due to the order declarations and you are unable to locate the reason, make a new copy and re-enter your definitions.Each configuration has a syntax description where names within angles < > are user selected labels and all other words shown are reserved. Also provided are examples of configurations.Numbers used are expected to be in decimal notation, unless you specify otherwise. Hexadecimal numbers are entered by preceding the hexadecimal number with a "0x". For details on notational conventions, refer to the appropriate assembly language manual.The configuration file osarm.con is the input file for the confarm configuration program. After running confarm, the OSE Epsilon for ARM kernel (osarm.*) will be generated.For more information about system generation, see “Building a System” on page 77.
AR
M K
erne
l
44 • Configuring OSE Epsilon for ARM User’s Guide / 4.6
Configuration is described in:
• “C Compiler” on page 45
• “Target Name” on page 46
• “CPU Type” on page 47
• “Memory Model” on page 48
• “Debug Option” on page 49
• “Buffer Check Option” on page 50
• “Stack Check Option” on page 51
• “Option Debugger” on page 52
• “Option Conditional Halt” on page 53
• “Option Dispatcher in RAM” on page 54
• “Pool Size” on page 55
• “Buffer Sizes” on page 56
• “Interrupt Stack” on page 57
• “Temporary Stack” on page 58
• “Error Handler” on page 59
• “Start Handlers” on page 60
• “Swap Handler” on page 61
• “Send Handler” on page 62
• “Receive Handler” on page 63
• “Power On Handler” on page 64
• “Power Off Handler” on page 65
• “Idle Handler” on page 68
• “Fast interrupts as IRQ:s” on page 69
• “Interrupt Processes” on page 70
• “Timer Interrupt Processes” on page 71
• “Prioritized Processes” on page 72
• “Link Handler Processes” on page 73
• “Background Processes” on page 74
• “Enable Wake Up” on page 75
AR
M K
erne
l
User’s Guide / 4.6 C Compiler • 45
2
2
4.1 C CompilerDescription: Defines the used C compiler product.
Supported compilers are: ARM (ARM Ltd.) ADS/RVCT, IAR (IARSystems AB) and GNU GCC.
The option SINGLECHIP enables the generation of a Single-Chip ver-sion. This is very useful for projects which need limited memory con-sumption. There is only one restriction for the Single-Chip version: AllOSE data segments must reside in the first 64 Kbyte memory range.
This declaration must be the first entry in osarm.con.
This declaration must always be present.
Syntax: COMPILER<type>[,SINGLECHIP]
Parameter: type ARMIARGNU
SINGLECHIPEnables the generation of a system with limited memoryconsumption.
Example COMPILER ARM
COMPILER IAR,SINGLECHIP
AR
M K
erne
l
46 • Target Name User’s Guide / 4.6
4.2 Target NameDescription: This entry allows you the give your target a specific name.
The target name will be displayed in the OSE Illuminator system leveldebugger and can be used in OSE Linkhandlers to access targets in a dis-tributed environment.
Syntax: TARGET_NAME <name>
Parameter: name User defined character string
Example TARGET_NAME motcon
AR
M K
erne
l
User’s Guide / 4.6 CPU Type • 47
2
2
4.3 CPU TypeDescription: The possible CPU types are ARM7TDMI (includes all ARMv4T deriv-
atives), ARMv5T (includes also ARMv5TE) and XSCALE.This declaration must always be present.
Syntax: CPU <type>
Parameter: type ARM7TDMIARMV5TXSCALE
Example CPU ARM7TDMI
AR
M K
erne
l
48 • Memory Model User’s Guide / 4.6
4.4 Memory ModelDescription: Defines the endian type. Select LITTLE for little endian and BIG for big
endian.
This declaration must always be present. This item must correspond withcompile and debug options.
Syntax: MEMORY_MODEL <model_type>
Parameter: model_type LITTLEBIG
Example MEMORY_MODEL LITTLE
AR
M K
erne
l
User’s Guide / 4.6 Debug Option • 49
2
2
4.5 Debug OptionDescription: The debug option enables some of the error checks and also makes it pos-
sible to use the Illuminator debugger. If debug is not enabled, there is asubstantial reduction of the code size of the operating system. There isalso an increase in execution speed. This declaration must always bepresent.
Syntax: DEBUG <state>
Parameter: state YESNO
Example DEBUG YES
AR
M K
erne
l
50 • Buffer Check Option User’s Guide / 4.6
4.6 Buffer Check OptionDescription: If a user process obtains a buffer from ALLOC, it must not write beyond
the end of that buffer. Should the process do so, this will probably causeerratic system crashes. Such errors are difficult to detect. If you select thebuffer check option, OSE Epsilon for ARM will detect buffer overwrite er-rors and also suggest the process responsible.
Without the buffer check option only scanned information will be avail-able after a buffer handling error.
If buffer check is selected, each buffer will require another four bytes.There is also a substantial performance penalty for the SEND, RE-CEIVE, RECEIVE_W_TMO, RECEIVE_ALL_BUT and ALLOC,FREE system calls.
The buffer check option requires the debug option (see “Debug Option” onpage 49). This declaration must always be present.
Syntax: BUFFER_CHECK <state>
Parameter: state YESNO
Example BUFFER_CHECK YES
AR
M K
erne
l
User’s Guide / 4.6 Stack Check Option • 51
2
2
4.7 Stack Check OptionDescription: It is a fatal error to run out of stack for a process. The system will crash
and it may prove very difficult to locate errors of this kind. If stack checkis selected the operating system will check for failed stacks and the erro-neous process may be revealed. It will check the interrupt stacks, thetemp stack an the current process stack.
The stack check will be executed at every system tick.
This declaration must always be present.
Syntax: STACK_CHECK <state>
Parameter: state YESNO
Example STACK_CHECK YES
AR
M K
erne
l
52 • Option Debugger User’s Guide / 4.6
4.8 Option DebuggerDescription: This option is used to enable the possibility to connect the OSE Illumi-
nator System Level Debugger.
Syntax: OPTION DEBUGGER,<type>
Parameter type NONo system level debugger will be used.
ONCHIP, <max. trace>,<max. evact>This option is used to enable the possibility to connect theOSE Illuminator System Level Debugger over a serialline interface to the target system. Please consult the OSEIlluminator manual for more information.<max. trace>Maximum number of entries in the trace ring buffer of thetarget OSE debugger.<max. evact>Maximum number of entries in the evact table of the tar-get OSE debugger.
Example
OPTION DEBUGGER,NO
AR
M K
erne
l
User’s Guide / 4.6 Option Conditional Halt • 53
2
2
4.9 Option Conditional HaltDescription: If this option is selected, timer interrupt processes are taken into account
when calculating the time possible to halt the system at conditional halt(system call cond_halt).
This declaration is optional. If this entry is omitted, the default setting is:NO.
Syntax: OPTION COND_HALT_W_TIMINT,<switch>
Parameter: switch YESNO
Example OPTION COND_HALT_W_TIMINT,YES
AR
M K
erne
l
54 • Option Dispatcher in RAM User’s Guide / 4.6
4.10 Option Dispatcher in RAMDescription: If this option is selected, the OSE dispatcher will be placed in a separate
section which can be placed in RAM. The section name is OSEDSP(ADS 1.1, GNU) or FARFUNC_A_I (IAR). This can improve the per-formance of the system. The size of the dispatcher is 128 bytes.
This declaration is optional. If this entry is omitted, the default setting is:NO.
Syntax: OPTION DISPATCHER_IN_RAM,<switch>
Parameter: switch YESNO
Example OPTION DISPATCHER_IN_RAM,YES
AR
M K
erne
l
User’s Guide / 4.6 Pool Size • 55
2
2
4.11 Pool SizeDescription: Defines the size of the buffer pool in bytes. The pool must be able to con-
tain all buffers used at any one time.
This declaration must always be present.
The Pool will be placed in section OSEPOOL.
Syntax: POOL <size>
Parameter: size The buffer pool size in bytes.48..4’294’967’292
The limits are determined by system design. (Refer toMemory Requirements in Building a System.)
Example POOL 2000
AR
M K
erne
l
56 • Buffer Sizes User’s Guide / 4.6
4.12 Buffer SizesDescription: There are eight buffer sizes available. Each of these can be selected in the
range 4..4’294’967’292. When a process allocates a buffer, one of theeight buffer sizes will be chosen. The buffer size chosen will be largeenough to contain the requested number of bytes. If the size is larger thanrequired, a number of bytes will be unused.
In order to waste as little memory as possible, you should select buffersizes to match those of the buffers your system will actually use.
NOTE that the sizes must be declared in ascending order and must be amultiple of 4 (integer aligned).
This declaration must always be present.
Syntax: BUFFERSIZES <size1>,<size2>,<size3>,<size4>,<size5>,<size6>,<size7>,<size8>
Parameter: size1 Buffer size 1.size2 Buffer size 2.size3 Buffer size 3.size4 Buffer size 4.size5 Buffer size 5.size6 Buffer size 6.size7 Buffer size 7.size8 Buffer size 8.
NOTE that sizes must be stated in order of increasing size.
Range: 4..4’294’967’292. Size 0 is not permitted.
Example BUFFERSIZES 32,64,128,256,1024,2048,4096,8192
AR
M K
erne
l
User’s Guide / 4.6 Interrupt Stack • 57
2
2
4.13 Interrupt StackDescription: This declaration reserves space for the interrupt stack.
The stack is placed in section OSESTACK.
Syntax: ISTACK_SIZE <stacksize>,[<second>]
Parameter: stacksize The extra stack space in bytes. The limits are determinedby system design.
second The second stack is used by nested interrupts only. Withnested interrupts, the first stack is used to save the regis-ters, and the second is used for local variables of the inter-rupt functions.
Size estimation:(max nesting level - 1) * 60 for the first stack(max nesting level ) * (max stack usage) for the secondstack.
Example ISTACK_SIZE 2048
AR
M K
erne
l
58 • Temporary Stack User’s Guide / 4.6
4.14 Temporary StackDescription: This section reserves space for the temporary stack.
The stack is placed in section OSESTACK.
Syntax: TEMP_STACK_SIZE <stacksize>
Parameter: stacksize The extra stack space in bytes.
Example TEMP_STACK_SIZE 160
AR
M K
erne
l
User’s Guide / 4.6 Error Handler • 59
2
2
4.15 Error HandlerDescription: This declaration is used to inform the operating system which procedure
to call on an error.
This declaration is optional and need be present only if an error handleris used.
Syntax: ERROR_HANDLER <name>
Parameters: name The name of your error handler procedure.
Example ERROR_HANDLER ERROR_DISPLAY
AR
M K
erne
l
60 • Start Handlers User’s Guide / 4.6
4.16 Start HandlersDescription: A start handler is called before OSE Epsilon for ARM is initialised.
Initialisation that must take place with interrupts disabled or before anyprocess is started should also be put in a start handler.
A start handler written in C may be declared as:
void my_init_of_global_data(void){
.
.
.};
This declaration is optional and need be present only if test handlers areneeded.
Syntax: START_HANDLER <name>
Parameters: name The name of your test handler procedure.
Example SSTART_HANDLER RAM_TESTSTART_HANDLER my_init_of_global_data
AR
M K
erne
l
User’s Guide / 4.6 Swap Handler • 61
2
2
4.17 Swap HandlerDescription: The swap handler is called by OSE Epsilon for ARM each time a new proc-
ess is about to be swapped in and also when entering IDLE mode.
A swap handler is mostly used by debuggers to collect statistics on proc-ess performance.
Interrupts are disabled while calling the swap handler. Interrupts mustnot be re-enabled by the handler and no system calls may be used by thehandler.
A swap handler written in assembly receives the ID of the next processto run in R0.
The swap handler uses the temporary stack. The process ID for the 'idleprocess' is 0xFF.
A swap handler written in C may be declared as:
void swap_log(PROCESS prev_id, PROCESS next_id)
{...
};
This declaration is optional and need be present only if a swap handler isneeded.
Syntax: SWAP_HANDLER <name>
Parameters: name The name of your swap handler procedure.
Example SWAP_HANDLER swaplog
AR
M K
erne
l
62 • Send Handler User’s Guide / 4.6
4.18 Send HandlerDescription: The send handler is called by OSE Epsilon for ARM each time a signal is
sent to any process.
A send handler is mostly used by debuggers to collect signal trace lists.
Interrupts are disabled while calling the send handler. Interrupts must notbe re-enabled by the handler and no system calls except SENDER andSIGSIZE may be used by the handler.
A send handler written in C may be declared as:
void send_log(PROCESS mysender,PROCESS myaddressee,
union SIGNAL *sig){
.
.
.};
This declaration is optional and need be present only if a send handler isneeded.
Syntax: SEND_HANDLER <name>
Parameters: name The name of your send handler procedure.
Example SEND_HANDLER siglog
AR
M K
erne
l
User’s Guide / 4.6 Receive Handler • 63
2
2
4.19 Receive HandlerDescription: The receive handler is called by OSE Epsilon for ARM each time a signal
is received by a process.
A receive handler is mostly used by debuggers to collect signal trace lists.
Interrupts are disabled while calling the receive handler. Interrupts mustnot be re-enabled by the handler and no system calls except SENDERand SIGSIZE may be used by the handler.
A receive handler written in C may be declared as:
void receive_log(PROCESS mysender,union SIGNAL *sig)
{...
};
This declaration is optional and need be present only if a receive handleris needed.
Syntax: RECEIVE_HANDLER <name>
Parameters: name The name of your receive handler procedure.
Example RECEIVE_HANDLER siglog
AR
M K
erne
l
64 • Power On Handler User’s Guide / 4.6
4.20 Power On HandlerDescription: A power on handler must be present if the system shall be able to warm
start after it has been powered down by the power off handler. This canhappen as a result of using either of the system calls POWER_FAIL orCOND_HALT.
This procedure checks if a warm or a cold start should be performed. Itreturns a value other than zero if a warm start is required.
A warm start may be used only when the entire memory remains validsince the last time the system was running, and if the system was shutdown by the power off handler.
If a warm start is required, all I/O ports must be initialized by the poweron handler to the values that were current at the time of thePOWER_FAIL call.
If a cold start is required, I/O ports may instead be initialised by the proc-esses using the I/O.
The power on handler can use the system call ADD_TICKS to let theOSE Epsilon for ARM time system compensate for the time that the systemhas been powered down. This is particularly useful if the system waspowered down as a consequence of the COND_HALT system call. Seepower off handler for information about how to use ADD_TICKS safely.
A power on handler should be written in assemlber because the C systemis not yet setup.
A power on handler written in assembler should return a int value in R0.
This declaration is optional and need be present only if thePOWER_FAIL system call is utilised.
Syntax: POWER_ON_HANDLER <name>
Parameters: name The name of your power on handler procedure.
Example POWER_ON_HANDLER my_power_on
AR
M K
erne
l
User’s Guide / 4.6 Power Off Handler • 65
2
2
4.21 Power Off HandlerDescription: A power off handler is needed if either of the system calls
POWER_FAIL or COND_HALT are to be used.
The power off handler acts as a server to both these system calls. In thecase of POWER_FAIL the power off handler should prepare the systemfor a warm start by performing an orderly shut down.
The other option is to handle COND_HALT. This mechanism is intend-ed to put the system in a 'light sleep' that enables the system to conservepower while still maintaining operation of time-outs, delay and timer ifCONDHALT_W_TIMER is set, and possible some other external hard-ware. In this case the timer hardware should be setup to wake up the sys-tem after a time that is determined by the idle_ticks parameter. Thehandler should then proceed by either halting the processor or perform-ing an orderly shut down. The choice depends on the available hardwarecapabilities of the system. Perhaps the system shall be halted for shortsleep time and powered down for long sleep times.
The power off handler is called with interrupts disabled.
The parameter is
idle_ticks: zero => power failnot equal zero => cond_halt ticks
A power off handler written in C may be declared as: (This example dealswith COND_HALT by halting the processor)
void my_power_off(OSTICK idle_ticks){
If (idle_ticks != 0){
<Prepare timer to wake up after idle_ticks><Halt processor><Re-initialies timer and call ADD_TICKS>
}else{
<Save current state of all I/O ports.><Set warm start flag.><Create ram checksum and save it.><Turn off power and enforce hardware reset.>
}}
AR
M K
erne
l
66 • Power Off Handler User’s Guide / 4.6
The above pseudo code contains a few tricky parts that need further ex-planation. They concern handling of the timer and the halt mechanism:
It is assumed that the halt mechanism wakes up by an interrupt. It shouldnever fall asleep if an interrupt is pending when the halt operation is per-formed. It is also assumed that the processor continues executing on theinstruction after halt when the interrupt arrives.
The interrupt should be serviced as soon as a interrupts are enabled(when the handler is exited). It is imperative that the halt mechanism doesnot lack any of these properties. Otherwise the algorithm described herewill be prone to dead-locks.
One tricky aspect o handling timer chips is that they may wrap aroundand cause an interrupt during the execution of the handling code. Thesoftware must deal with this in some way.
The idle_ticks parameter defines how many ticks may be skipped with-out disturbing the OSE Epsilon for ARM time-out, delay and timer system.The timer hardware should be adjusted to generate an interrupt that manysystem ticks later than planed. E.g. if idle_ticks is 3 and the timer hard-ware has 27% of a tick time remaining until the next interrupt, it shouldbe reinitialized to generate an interrupt after 3,27 tick times. It is also pos-sible that the timer issues an interrupt during the execution of this code,e.g. resulting in a pending interrupt and 99% of a tick time until the nexttick. This must be detected and countered. In this case by initialising thetimer to 2.99 tick time and clearing the pending interrupt.
The processor can wake up from halt by any interrupt. I.e. it could bewoken up either by a timer interrupt or another interrupt, whichever oc-curs first. The software should be able to handle both cases, perhaps bychecking if a timer interrupt is pending. (Remember that interrupts aredisabled during the execution of the handler.)
The timer should be re-synchronised to generate interrupts at tick inter-vals. This should be done without disturbing any pending interrupts.
The system call add_ticks should be called with the number of ticks thathave been skipped during the halt time. This value should never be morethan the idel_ticks parameter. Note that the time will usually be one morethan the idle_ticks parameter if the time expired. In this case the last tickshould be handled by a call to OSE_TIMER_ENTRY, for more informa-tion see appendix. This will happen naturally when the system handlesthe pending interrupt, provided that the interrupt is not cleared by the re-initialisation of the timer.
AR
M K
erne
l
User’s Guide / 4.6 Power Off Handler • 67
2
2
If the system sleeps by powering down instead of by using a halt mech-anism, the code for reinitializing the timer and updating the system timermust reside in the power on andler.
This declaration is optional and need be present only if either thePOWER_FAIL or the COND_HALT system call is utilised.
Syntax: POWER_OFF_HANDLER <name>
Parameters: name The name of your power off handler procedure.
Example POWER_OFF_HANDLER my_power_off
AR
M K
erne
l
68 • Idle Handler User’s Guide / 4.6
4.22 Idle HandlerDescription: The Idle Handler is called whenever no processes are in the ready state
(i.e. no processes want the CPU to execute).
The Idle Handler uses the temporary stack. Consult also “TemporaryStack” on page 58.
Note that the Idle Handler must never end. It is an error for an Idle Han-dler to execute a return statement.
This declaration is optional and need be present only if an idle handler isneeded.
Syntax: IDLE_HANDLER <name>
Parameters: name The name of your idle handler procedure.
Example IDLE_HANDLER my_idle
AR
M K
erne
l
User’s Guide / 4.6 Fast interrupts as IRQ:s • 69
2
2
4.23 Fast interrupts as IRQ:sDescription: If you plan to use fast interrupts (FIQ:s) as normal interrupts set this op-
tion to YES. FIQ:s will then be disabled and enabled at the same time asIRQ:s. If this option is NO FIQ:s are not touched by the OSE Epsilon forARM kernel
Syntax: FIQ_AS_IRQ <switch>
Parameters: switch YESNO
Example FIQ_AS_IRQ YES
.
AR
M K
erne
l
70 • Interrupt Processes User’s Guide / 4.6
4.24 Interrupt ProcessesDescription: Enter the names of the interrupt processes in your system.
Note that several steps are needed before an interrupt process is com-pletely installed:
• The interrupt process must be declared.• The interrupt handler must be modified to recognise the interrupt source,
and call the interrupt process entry code.• The interrupt process entry code is created by OSE Epsilon for ARM. When
calling the entry code from your interrupt handler, add “OSE_” to the named declared below. The interrupt process should not be called directly from the interrupt handler.
• The interrupt process is called from ARM-mode. Therefore “interworking” should be enabled for thumb-mode routines.
• The interrupt generating hardware must be initialised.
These declarations are optional and need be present only if interruptprocesses are needed.
Syntax: INT_PROC <process_name>
Parameter: process_name The name of a process.
Example S
INT_PROC bandersnatchINT_PROC LINK_TRANCEIVERINT_PROC SERIAL_0
AR
M K
erne
l
User’s Guide / 4.6 Timer Interrupt Processes • 71
2
2
4.25 Timer Interrupt ProcessesDescription: Enter the names of the timer-interrupt processes in your system.
Timer-interrupt processes are called with configurable period. The peri-od between calls is expressed in system ticks. The period is1..4’294’967’295.
These declarations are optional and need be present only if timer-inter-rupt processes are needed.
Syntax: TI_PROC <process_name>,<call_interval>,[,init]
Parameters: process_name The name of a process.
call_interval The interval between calls to the process.Range:1..4’294’967’295.
init Initial delay. This an optional parameter.
A timer interrupt process starts normally at time 0 at sys-tem start. You can give an initial delay before the interruptwill be started. Range: 1..4’294’967’295.
Example
TI_PROC tnuctipun,155TI_PROC poll,100,10
AR
M K
erne
l
72 • Prioritized Processes User’s Guide / 4.6
4.26 Prioritized ProcessesDescription: Enter the names of the prioritized processes in your system.
A priority is specified for each process A process of higher priority runsbefore every process of lower priority.
If several processes have the same priority they are chosen from in a firstready, first served fashion. At startup the prioritized processes are madeready in the order they appear in the osarm.con file.
These declarations are optional and need be present only if prioritizedprocesses are needed.
Syntax: PRI_PROC <process_name>,<stacksize>,<priority>[,mode]
Parameters: process_name The name of a process.
stack_size The requested size in bytes for the stack of the process.
Range: 160..4’294’967’295.
priority The requested priority for the process.0 = highest priority,31 = lowest priority.
mode Optional CPU mode SYS (default)USR
Example PRI_PROC my_process,128,1PRI_PROC outsider,128,19PRI_PROC SLAVER,128,15
AR
M K
erne
l
User’s Guide / 4.6 Link Handler Processes • 73
2
2
4.27 Link Handler ProcessesDescription: A Link Handler is an ordinary prioritized process. Link handlers are
needed to build distributed OSE systems with message based transparentcommunication.
The Link Handler will receive all signals which are sent to processes witha pid of higher than 255.
This entry will assign a name and define some parameters for the linkhandler.
There is only one link handler allowed in an OSE Epsilon for ARM system.
Syntax: LINKHANDLER <process_name>,<stacksize>,<priority>[,mode]
Parameters: process_name The name of the link handler process.
stack_size The requested size in bytes for the stack of the process.
Range: 160..4’294’967’295.
priority The requested priority for the process.0 = highest priority,31 = lowest priority.
mode Optional CPU mode SYS (default)USR
Example LINKHANDLER my_link,128,10
AR
M K
erne
l
74 • Background Processes User’s Guide / 4.6
4.28 Background ProcessesDescription: Enter the names of the background processes in your system.
All background processes are of equal priority and the order in whichthey are declared is of no importance.
These declarations are optional and need be present only if backgroundprocesses are needed.
Syntax: BG_PROC <process_name>,<stacksize>,<timeslice>[,mode]
Parameters: process_name The name of a process.
stack_size The requested size in bytes for the stack of the process.
Range: 160..4’294’967’295.
timeslice The number of system ticks the process will be allowed torun before being swapped out.
. Range: 160..4’294’967’295.
mode Optional CPU mode SYS (default)USR
Example SBG_PROC background_tests,128,12BG_PROC THRINT,1024,1
AR
M K
erne
l
User’s Guide / 4.6 Enable Wake Up • 75
2
2
4.29 Enable Wake UpDescription: This option enables the operating system to activate the interrupt process
or timer interrupt process, if a signal is received from a prioritized orbackground process. System call wake_up() must be used to determinewhether it was activated by hardware or by the operating system.
Syntax:ENABLE_WAKE_UP <state>
Parameter: state YESNO
Example ENABLE_WAKE_UP YES
AR
M K
erne
l
76 • Enable Wake Up User’s Guide / 4.6
AR
M K
erne
l
User’s Guide / 4.6 Building a System • 77
2
2
5 Building a SystemTo build a system, do the following:
1. Determine the specifications of the system, such as functions, speed requirements, environment etc.
2. Design the system, i.e. determine hardware configuration, memory usage, interrupt structure, processes and process interface.
3. Select the files you need from the OSE Epsilon for ARM installation and copy them to your working directory.
4. Modify the system files for the used board. This should include at least the system initialization functions, the interrupt handler and a tick timer setup file. You can find examples of such files in the Board Support Package delivery.
5. Configure the system, that is, enter configuration data into the configuration file osarm.con.
Run confarm.exe to create the assembler file osarm.*. Ensure you have the correct version of osarm.con. File extensions differ from compiler to compiler(e.g. ARM: *.s, GNU *.S, IAR: *.s79).
6. Generate the ARM kernel by assembling the file osarm.*.
7. Write your signal specifications. A reasonable approach is to have a small set of related signals in each include file. If you are using the OSE Soft Kernel, you should keep your signal specifications consistent with Softkernel demands.
8. Write your processes and compile/assemble them.
9. If you have selected the debug option (OPTION DEBUGGER) in the osarm.con configuration file the Debug Kernel will be generated and you also need a communication module to connect the Debug Kernel to the host. For an asynchronous serial line connection, you can find a driver in the OSE Epsilon for ARM Board Support Package.
10.We recommend that you also write an error handler if you have a display device in your target system. An error handler may display errors quickly and conveniently during debugging
11.Link the generated kernel, the bsp system files, your processes, your handlers and the compiler library together to form the target binary file.
AR
M K
erne
l
78 • Building a System User’s Guide / 4.6
The following diagram shows the process for building a system:
See also:
• “System Files” on page 79
• “Configuration” on page 79
• “Configuration Utility” on page 79
• “Illuminator System Level Debugger” on page 79
• “Assembly-Time Errors” on page 80
osarm.anc ose.h
osarmi.anc ose_i.hconfarm
osarm.con
Configuration
Processes anduser files writtenin assembler
Processes anduser files writtenin C
Assembler
Assemble Compile
clib Link
Include Include
osarm.mac
Include
(osarm_sc.mac)
SystemFiles
osarm.s (ARM)osarm.s79 (IAR)osarm.S (GNU)
ose_usr.h
AR
M K
erne
l
User’s Guide / 4.6 System Files • 79
2
2
5.1 System FilesTo setup an OSE Epsilon for ARM system, you will need a few system files. These are:
• crt0.*
• inthdir.*
• timer_setup.*
File extensions will differ from compiler to compiler (e.g. ARM: *.s, GNU *.S, IAR: *.s79).
Examples of these system files can be found in the OSE Epsilon for ARM board support package delivery. If your board is not supported, you can use these system files as templates.
5.2 ConfigurationThe OSE operating system can be configured to have completely different characteristics depending on the trade-offs you want to make between speed, memory consumption and code size. The configuration is accomplished by entering the desired values into the osarm.con configuration file.As shipped, osarm.con contains a configuration suitable for a typical system. Browse through it and change the settings as required for your application. If you are unsure about a setting use the current setting. However, you must always define the names of the processes in your particular system.
5.3 Configuration UtilityWhen the configuration is satisfactory, you must run the confarm.exe configuration utility. This will create the kernel file osarm.*. The confarm command syntax is:confarm input_file [output_file]
For every change in the osarm.con configuration file, the confarm.exe utility must be executed again.
5.4 Illuminator System Level DebuggerIf you have selected the debug option (OPTION DEBUGGER) in the osarm.con configuration file the Debug Kernel will be generated.You also need a communication module to connect the debug module of the kernel to the host. For an asynchronous serial line connection a serial driver is included in the board support package delivery.
AR
M K
erne
l
80 • Assembly-Time Errors User’s Guide / 4.6
5.5 Assembly-Time ErrorsMany configuration errors are detected by OSE when you run the configuration utility and assemble the operating system. OSE does not attempt to detect errors which the assembler will find. Assembler error messages should enable you to correct most of these errors.Never attempt to correct assembly time errors until all OSE Epsilon for ARM configuration errors have been corrected. This is because OSE Epsilon for ARM configuration errors also generate assembler errors.
AR
M K
erne
l
User’s Guide / 4.6 System Design • 81
2
2
6 System DesignOSE Epsilon for ARM is a fast, compact, real-time operating system for the ARM line of microprocessors from ARM Ltd.OSE Epsilon for ARM is designed exclusively to fit the peculiarities of the ARM processor family. Every conceivable effort has been made making OSE Epsilon for ARM as fast as possible. The entire system is written in heavily optimized assembler. The data structures are designed to fit the processor memory structure and the specific system calls. Tasks which traditionally have been left to the user to accomplish as best he can has been taken over by the operating system. Most of the design effort has been spent in selecting and tuning a set of system calls which provides maximum system performance.Speed is not always paramount. At times it is necessary to preserve code memory. This can be done in two ways when using OSE Epsilon for ARM. In a small system the size of the operating system itself may be a problem. Should such be the case you may use OSE in a minimum code configuration. If the system is large, the size of the operating system will be a minor problem since it is inherently small.A system under OSE Epsilon for ARM consists of a number of independent subprograms called processes. A process may be written to some extent as if it had the entire CPU for its own exclusive use.By assigning a priority to each process, OSE Epsilon for ARM ensures that the right process is always executing. An event which requires another process with a higher priority to execute, forces an immediate switch of process. This scheme ensures fast response to important events. Processes co-operate by exchanging signals. A process may send a signal to the mailbox of another process to inform the receiver of an event or to respond to an event. Signal transmissions often cause execution to switch to another process (a task switch).A signal is a dynamically allocated message buffer containing a signal number and an optional data structure.Signal numbers are used to select which signals to receive, while leaving others in the mailbox of the receiving process. It is possible to ignore events which are unimportant at the moment simply by selecting which signals to receive. Other processes use the CPU while a process is waiting for a signal to arrive. Unused message buffers are stored in the central buffer pool until allocated by a process. Only one process at a time may access a signal (or message buffer), thereby eliminating conflicts.
If a process needs to suspend execution for a specific interval of time, it calls OSE which monitors time and activates other processes during the wait.
AR
M K
erne
l
82 • System Design User’s Guide / 4.6
For more information on system design, see:
• “System Creation Cycle” on page 83
• “Processes” on page 84
• “Starting and Stopping Processes” on page 93
• “Signals” on page 94
• “Fast Semaphores” on page 97
• “Semaphores” on page 97
• “Memory Utilisation” on page 98
• “Speed Considerations” on page 102
• “System Start” on page 104
• “Writing the Interrupt Handler” on page 104
• “Writing a Link Handler” on page 106
• “Writing an Error Handler” on page 108
AR
M K
erne
l
User’s Guide / 4.6 System Creation Cycle • 83
2
2
6.1 System Creation CycleThis chapter contains information on how to create a system using OSE Epsilon for ARM. It discusses major design parameters such as memory usage, speed factors and interrupts. It also takes you through the various phases of programming, from writing the first line of the first process until catching the last bug. Specification techniques are outside the scope of the manual, however.The first step in the design process is to divide the system into a number of processes. Concurrent events should be handled by separate processes. That is, if two things may occur at the same time, they should be handled by different processes. For example, in a terminal, the operator may be typing at the keyboard while the computer sends characters to the terminal.In the division of work between processes, one important consideration is to minimize the interface between processes. That is, they should have as little as possible to do with each other. Another design consideration is to avoid very small and very large processes. It is also desirable not to have processes share hardware.Once the system is divided into processes, the interface between them is described by defining the signals to be exchanged. The processes, the sequence of events and timing are probably described using some specification and description language.When the system has been designed, the processes are written, either in C or assembly. We suggest that you use the process templates provided in the appendixes. Each process is put in a separate file and these are compiled/assembled.When this is done, the operating system must be assembled.Then the system is linked. The system is now ready to run. It is possible that errors have been made in the system design, in the writing of the processes, in the configuration of the operating system or in the linking command. Should such be the case, the error(s) must be detected and located during the process of debugging. The OSE Illuminator debugger is a useful tool when trying to find errors.
AR
M K
erne
l
84 • Processes User’s Guide / 4.6
6.2 ProcessesA process is an independent program running under OSE. In every instant of time, the most important process ready to run is running. As soon as a more important process wants to run the current process is removed from the CPU and the new process is entered and allowed to run. This is called a task switch. If you are running a system without OSE, the processor will often find itself unable to respond quickly to an event since the wrong part of the program is running and continues to do so for some time.There are several types of processes to allow you to run each part of your program at the right moment. The process types differ mainly in the way in which they are activated and in the way they use memory. The total number of processes of all types may not exceed 254.Each process is associated with a unique process identity, which is used in system calls to select the process. This identity is allocated by the operating system during system start, and it is placed in a global variable where it can be accessed by other processes. This variable is named as the process with an appended underscore character. E.g. a process named "keyboard" has an id which is placed in a variable named "keyboard_".In the ..\example directory of the OSE Epsilon for ARM Installation you will find process example files.Processes are further described in:
• “Prioritized Processes” on page 85
• “Background Processes” on page 86
• “Interrupt Processes” on page 87
• “Timer Interrupt Processes” on page 88
• “Selecting Process Type” on page 89
• “Process Include Files” on page 90
• “Process Declarations in C” on page 91
• “Process Declarations in Assembler” on page 92
• “Process Design Rules” on page 93
AR
M K
erne
l
User’s Guide / 4.6 Prioritized Processes • 85
2
2
6.2.1 Prioritized ProcessesPrioritized processes are the most common processes in a typical system.Prioritized processes have a strict order of priority. The highest priority process will always run before every other process. The lowest priority process will be allowed to run only when no other prioritized process is ready. If two processes are assigned the same priority, the choice of precedence between the two processes is made by OSE Epsilon for ARM.When a process has no further work to do for the moment, it becomes not ready. A process is not ready when it is waiting for a message or when it is waiting for a delay to end or when it is waiting at a semaphore. A process is swapped out from the CPU when it becomes not ready or when a process of higher priority becomes ready. Note that a process may be interrupted between almost any two assembler instructions and in the middle of any C instruction.A process is swapped in if all processes of higher priority are not ready and the process itself is or becomes ready.A prioritized process may use all system calls. When a prioritized process returns from a call to RECEIVE it may be certain that a signal is available.Note that a prioritized process must never end. When its task is done it should loop back to the beginning and wait for another request for its services. If it is certain that it will not again be needed, it may call STOP to stop itself. It is an error for a process to execute a return statement.Prioritized processes may be written either in assembly or C.
AR
M K
erne
l
86 • Background Processes User’s Guide / 4.6
6.2.2 Background ProcessesThese are identical to prioritized processes except that they do not have priority. A background process will only be allowed to run when no prioritized process is ready. The time left over when no prioritized process is running is divided between ready background processes. Running background process is switched by the operating system at user defined intervals.A background process is allowed to execute until it becomes not ready or a prioritized process becomes ready or until the background process has executed for the duration of the user defined interval. Background processes may be written either in assembly or C.
AR
M K
erne
l
User’s Guide / 4.6 Interrupt Processes • 87
2
2
6.2.3 Interrupt ProcessesAn interrupt is a hardware generated event which will cause the system to suspend the currently running background or prioritized process and turn control over to the interrupt process dedicated to that particular interrupt.There can exist only one interrupt process for each of the available hardware interrupt vectors. An interrupt process is called as a subroutine whenever its interrupt occurs, provided that no other interrupt is running.As long as an interrupt process is running, other interrupts are not permitted by the CPU. This means that interrupt processes prevent other interrupts, with the same or lower priority, while they execute. Interrupt latency for a certain interrupt process is therefore roughly determined by OSE Epsilon for ARM internal interrupt latency (see section on speed considerations) added to the execution time of the sum of all interrupt processes of the same or higher hardware priority. If this is not acceptable, interrupts can run outside the OSE Epsilon for ARM. In that case, no system call may be executed. An interrupt process will never become not ready, but is running from beginning to end each time it is activated. It is thus impossible for an interrupt process to wait for a signal or make a delay. Should it be allowed to do so it would stop almost all other activity in the system. If receive is called it will immediately return, even if there was no signal in the queue.No interrupt processes exist for the fast interrupt and illegal instruction trap. These events are served by optional handlers (NMI-handler, trap-handler etc.), which are not processes and may not execute any OSE system calls. OSE Epsilon for ARM does not interfere with these handlers except that the trap vectors are defined by the start-up code (init.s).Interrupt processes may be written in C or assembly. All interrupt processes share a common stack, which size is determined by the largest interrupt stack defined in the configuration.All interrupt processes will be enabled before the first prioritized processes called. Code which must be executed before interrupts are enabled, must reside in OSE_INIT_INTERRUPT which is located in the file INTHDLR.S. This code may also be included in the POWERON_HANDLER or in the START_HANDLER, both of which may be declared in the configuration file osarm.con.Note that several steps are needed before an interrupt process is completely installed:
• The interrupt process must be declared.
• The interrupt handler must be modified to recognise the interrupt source, and call the interrupt process entry code.
• The interrupt process entry code is created by OSE Epsilon for ARM. When calling the entry code from your interrupt handler, add OSE to the name declared in the osarm.con. The interrupt process should not be called directly from the interrupt handler.
• The interrupt process is called from ARM-mode. Therefore “interworking” should be enabled for thumb-mode routines.
• The interrupt generating hardware must be initialised.
AR
M K
erne
l
88 • Timer Interrupt Processes User’s Guide / 4.6
6.2.4 Timer Interrupt ProcessesTimer interrupt processes work like interrupt processes except for the manner in which they are called. For each timer interrupt process the user selects a number of system ticks to elapse between each call to the process.Timer interrupt processes should be short because they must be fast enough to permit all of them to execute during one system tick. If this is not possible, the process has been incorrectly designed, and parts of the task should be performed in a prioritized process. Timer interrupts have the same priority as the interrupt source, which generated the system tick. Other interrupts with higher priority then the timer interrupt may run as normal.Timer-interrupt processes are called with configurable period. The period between calls is expressed in system ticks. The period is 1..4’294’967’295.Timer-interrupt processes will start at the first timer-interrupt. Many timer-interrupt processes have variables which must be initialised in a START_HANDLER or as initialised static variables if the process is written in C.Timer interrupt processes may be written either in assembly or C.
AR
M K
erne
l
User’s Guide / 4.6 Selecting Process Type • 89
2
2
6.2.5 Selecting Process TypeInterrupt processes respond to events faster than any other process type. On the other hand, they must perform their task in a very short time. Imagine, for instance, an interrupt process whose task is to receive characters from the serial link. When a character has arrived, the process must quickly store it in a buffer. If this takes too long, the next character will be lost.When all the characters of a message have been received, some program must analyse and work with the message. This often takes much longer than the time between characters sent on the serial link.The interrupt process therefore sends the message to a prioritized process. The prioritized process will respond much slower than the interrupt, but, on the other hand, it can spend a long time working with the message. When the message is taken care of, the process waits for the next message, thus freeing the CPU for other processes. Prioritized processes also have different priorities thus enabling a more important process to interrupt a less important one.Suppose that a system has a routine which performs tests such as memory checks. These should be run as often as possible, but they should never subtract from system performance by using up time for more important work. Here, a background process is ideal, since it executes only when no interrupt or prioritized process is running.Timer-interrupt processes may be used for polling purposes. This type of task, for instance checking the status of a bit or a byte, can be done either by a background process or a timer-interrupt process. The difference is that a timer-interrupt process will check at well defined moments in time whereas background processes will check only when the system idles.If a measurement, for example a voltage, is to be sampled at regular intervals you might do this in a background process. It might sample the voltage, then make a delay, sample the voltage etc. If, however, other processes of higher priority should run, samples will be lost. To avoid this, a timer-interrupt process can be used since it would ensure that no samples are lost.
AR
M K
erne
l
90 • Process Include Files User’s Guide / 4.6
6.2.6 Process Include FilesThe user interface to OSE Epsilon for ARM is defined in a number of C header and assembler include files, which should be included in an OSE Epsilon for ARM application.
•Prioritized and Background Processes written in C must include the file ose.h.
• Prioritized and Background Processes written in C and running in USR modemust include ose_usr.h
•Interrupt and Timer Interrupt Processes written in C must include the file ose_i.h
•Prioritized and Background Processes written in Assembler must include the file osarm.anc.
• OSE Interrupt and Timer Interrupt Processes written in Assembler must include the file osarmi.anc.
AR
M K
erne
l
User’s Guide / 4.6 Process Declarations in C • 91
2
2
6.2.7 Process Declarations in C
6.2.7.1 Prioritized and Background Processes
Prioritized and Background Processes written in C must contain the declaration:OS_PROCESS (my_process) {}.
C Syntax:OS_PROCESS (<process_name>){
/* Code for process <process_name> */}
where the parameter process_name is the name of the process
6.2.7.2 Interrupt and Timer-Interrupt Processes
Interrupt and Timer-Interrupt Processes written in C must contain the declaration:OS_INT_PROCESS (my_process,int_src) {}.
You have to declare a second parameter for Interrupt and Timer-Interrupt Processes which holds the information from what source the interrupt occurred. The source can be:
1. The real hardware interrupt.
2. A signal sent to the process.
3. The fast semaphore was signalled.
C Syntax:OS_INT_PROCESS (<process_name>,<int_src>){
.
.
.}
Parameters: process_nameThe name of the process
int_src Source of interrupt (variable, type int):
0 Invoked by hardware interrupt
1 Invoked by signal sent to this process
2 Invoked by a SIGNAL_FSEM to this process. This ir-respective of the actual FSEM value. GET_FSEMgives no real value.
AR
M K
erne
l
92 • Process Declarations in Assembler User’s Guide / 4.6
6.2.8 Process Declarations in Assembler
6.2.8.1 Prioritized and Background Processes
Prioritized and Background Processes written in assembler must contain the declaration:PROCESSMY_PROCESS.
Assembler Syntax:PROCESS <process_name>; ; Process entrypoint. This is; ; where the process is called; ; from the operating system.
.
.
.
Parameter:process_nameThe name of the process
6.2.8.2 Interrupt and Timer-Interrupt Processes
Interrupt or Timer-Interrupt Processes written in assembler must contain the declaration:OS_INT_PROCESS <my_process>
For Interrupt and Timer-Interrupt Processes the register R0 holds the information from what source the interrupt occurred. The source can be:
1. The real hardware interrupt.
2. A signal sent to the process.
3. The fast semaphore was signalled.
Assembler syntax:OS_INT_PROCESS <process_name>; ; Process entrypoint. This is where the process; ; is called from the operating system.; ;; ; Test register R0 for source; ; of interrupt.
.
.END
Parameter:process_nameThe name of the processR0 Source of interrupt (register R0):
0 Invoked by hardware interrupt1 Invoked by signal sent to this process2 Invoked by a SIGNAL_FSEM to this process.
AR
M K
erne
l
User’s Guide / 4.6 Process Design Rules • 93
2
2
6.2.9 Process Design RulesThere are some mistakes in writing processes which can not be detected by OSE. They may cause a lot of trouble for, once made, they can be difficult to find.To avoid them, follow these few design rules carefully:
• Avoid doing several things at a time in a process. Concurrent work should be in different processes.
• Do not send lots of signals from a process without waiting for a reply once in a while. Remember that the receiving process may not run at all until the sender becomes not ready.
• Avoid taking advantage of knowledge on process priorities when designing a system. Priorities should be used only to promote fast response to the environment. A well designed system uses only a few priority levels.
• If a procedure is called from more than one process, the procedure must be re- entrant or interrupts must be disabled while the procedure is executing.
• Do not use global variables. If you must, then disable interrupts while accessing them.
• Do not share ports between processes. Shared ports must be treated as global variables.
• Never modify buffers after they have been sent to other processes.
• Avoid using large auto arrays in C processes. If these are instead declared static, stack requirements are much easier to determine.
• Make sure the correct version of osarm(i).anc is included in an assembler process.
When testing your system, always have a breakpoint set on the label Q_ERR in osarm.s. If this breakpoint is reached, an error has occurred. (For details on errors, refer to Run-Time Error Messages.) If you forget this breakpoint, the system will be unable to inform you of errors.
6.3 Starting and Stopping ProcessesA system where processes are stopped and started needs careful design, since it may easily hang. The start/stop feature is intended mainly for debugging. If start/stop is to be used, it is safer only to allow a process to stop itself.If processes are allowed to stop each other, a process may be stopped while communicating with a third process. That process may then hang and thus fail to respond to the first, stopping, process which in its turn may then hang. The result is that the stopped process may never be started again. There are several other ways to create unstable systems using start and stop, so do not use these calls unless you have to.
AR
M K
erne
l
94 • Signals User’s Guide / 4.6
6.4 SignalsSignals are messages sent between processes. Each message is a buffer, an area of memory, where processes may read and write data. A buffer may be used by many different processes, but only one process at a time may access a buffer. Signals not only carry data, they also initiate actions by the various processes.All processes can exchange signals, even those residing in other computers. (Through the use of a link handler.)Before a signal can be sent a buffer must be allocated and the data, if any, must be entered into the buffer. The signal number, which must always be present, is entered by the operating system when the buffer is allocated, but may be altered by the user if convenient. The signal number is always the first word of a buffer.When a process gains access to a signal buffer by allocating it or receiving it, the process becomes the owner of the buffer. Only the owner may perform operations on the buffer.Once a signal has been sent to another process it can no longer be accessed by the sending process. A process may select the signals it is interested in receiving at any particular moment. The process will then wait for signals to arrive. Meanwhile, other processes are allowed to execute.
AR
M K
erne
l
User’s Guide / 4.6 Using Signals In Processes • 95
2
2
6.4.1 Using Signals In ProcessesIt is a fatal error to write beyond the end of an allocated buffer. Such errors may be detected if you select the BUFFER CHECK option when configuring the system. If you do not, the system will simply crash and you will find it exceedingly difficult to find out why.When writing in C, the method for accessing and allocating buffers described below minimizes the risk for buffer overwrite errors. It also provides code which is easy to read. To achieve maximum speed you should manipulate the pointers yourself, preferably in assembly.Declare each signal as shown in the signal template. Each part of the signal buffer is endowed with a name in the structure declaration of the signal. Use the structure to decide the size of the buffer to allocate. (For a more detailed example, refer to Sample Signal.)Syntax:#define<SIG_NAME>(<value_1>)struct <sig_name> { SIGSELECT sig_no;
<member_type> <member>;..
};
union SIGNAL {SIGSELECT sig_no;struct <sig_name> <sig_name>;
};
union SIGNAL *<buf_ptr>;
<buf_ptr>=alloc(sizeof(<struct sig_name>),<SIG_NAME>);
To access the signal buffer:
<buf_ptr>-><sig_name>.<struct_member> = <value_1>;
Parameters:sig_nameThe name of the signalstruct_memberSome data of the signalSIG_NAMEA number 0..32767 which identifies the signal.value_1A variable name or number.
AR
M K
erne
l
96 • Buffer Transfer User’s Guide / 4.6
Example#define MY_SIGNAL (17)struct my_signal {
SIGSELECT sig_no;char character;
};
union SIGNAL {SIGSELECT sig_no;struct my_signal my_signal;
};
union SIGNAL *sig_ptr;
sig_ptr = alloc( sizeof(struct my_signal), MY_SIGNAL );
To access the signal buffer:
sig_ptr->my_signal.character = 0xd;
6.4.2 Buffer TransferAt times, buffers are used for other purposes than signal transmissions. Sometimes a buffer may be turned over to another process via a global variable instead of using SEND. If a buffer is transferred from one process to another and the other process tries to send or free that buffer, the result will be an error condition. The operating system will detect that someone is trying to free or send a buffer which he does not own. To avoid this, the process who wants to free/send the buffer must call RESTORE. RESTORE will then note that the calling process is the new owner of the buffer.
AR
M K
erne
l
User’s Guide / 4.6 Fast Semaphores • 97
2
2
6.5 Fast SemaphoresThere is no need to read this chapter unless you have serious response problems in your system.Fast semaphores are intended for those rare cases where user programs cannot use signals due to timing problems. For example, a fast semaphore may be used to count characters in a user implemented buffer between an interrupt process receiving characters and a prioritized process consuming characters.Fast semaphores work like this: A fast semaphore is a signed integer owned by a process. It is operated by system calls WAIT (WAIT_FSEM) and SIGNAL (SIGNAL_FSEM). Only the owner may wait at a fast semaphore. Other processes may signal it.The WAIT operation decrements the value of the semaphore and blocks the calling process (owner) if the result becomes negative. The caller is again allowed to run only if some other process makes the value of the semaphore non negative by issuing a SIGNAL operation.The SIGNAL operation increments the value of the semaphore. If there is a process waiting at the semaphore, it is released if the result becomes non negative.There is one fast semaphore associated with each prioritized or background process. This semaphore must be explicitly initialised by the process before it is referenced the first time by any process (using the system call SET_FSEM).The current value of a fast semaphore may be examined (GET_FSEM) so that semaphore overrun can be avoided.
6.6 SemaphoresSemaphores are somewhat similar to fast semaphores, but they differ in one very important aspect:A semaphore is not related to any specific process. Any background or prioritized process may wait at a semaphore, not just the owner. Any type of process may signal a semaphore.The main purpose of semaphores is to protect critical code sections from concurrent execution (so called mutual exclusion) without disabling interrupts. This is often done to protect global shared resources. If the compiler supports static initialisation of C structures this can be used to declare a semaphore at compile time.Semaphores are mainly used to ensure that only one process at a time is using a global shared resource. As soon as the process currently occupying the resource releases it, it will automatically be given to the next in its waiting queue. Use the wait_sem system call to get in line to use the resource as soon as possible and the signal_sem system call to releases it as soon as the resource is no longer needed.OSE also implements a simpler form of semaphores for exclusive use by the OSE kernel and associated products. For example, the FLUSH system call uses an internal semaphore to protect internal data structures.
AR
M K
erne
l
98 • Memory Utilisation User’s Guide / 4.6
6.7 Memory Utilisation
6.7.1 Global VariablesIt is not recommended to use global variables, that is variables used by more than one process.If processes use global variables/buffers there will be access problems. One process may access the first byte of such a variable, then a change of process occurs before the next byte is accessed. While the process is swapped out, some other processes may change the variable/buffer. Thus, the results of accesses to global variables are unpredictable.Global variables will make it impossible to use some of the most powerful debugging tools available when using OSE. The use of signals is recommended instead of global variables. Processes written using signals only, will also be easy to use in other processors, and in other projects.When designing using signals, simply let every piece of hardware be owned by a process. Other processes send signals to the owner when they need to access that particular hardware. All access problems are then avoided.One way of avoiding global variables is to design the hardware such that processes need not to share it. This is possible if the ports are organized in such a way that the bits needed by one process reside in one port.If global variables are used, interrupts must be disabled/enabled at each access, with the concomitant response time increases.
AR
M K
erne
l
User’s Guide / 4.6 Memory Requirements • 99
2
2
6.7.2 Memory RequirementsThe amount of code memory and data memory needed in your system is determined by system configuration and design. This section is intended to serve as a guideline when designing your hardware.
6.7.2.1 Memory Used By the Buffer Pool
The buffer pool is a major user of data memory. There are eight fixed, user selected, sizes of signal buffers. Estimate maximum number of buffers of each size used by your system. Each buffer also uses a 12 byte administration block (8 bytes in single-chip version). If the debug option is used, each buffer needs an additional eight bytes.Use the following formula to calculate buffer pool size
POOL = no_of_buffers_size1*size1+no_of_buffers_size2*size2+no_of_buffers_size3*size3+no_of_buffers_size4*size4+no_of_buffers_size5*size5+no_of_buffers_size6*size6+no_of_buffers_size7*size7+no_of_buffers_size8*size8
No_of_buffers is the maximum number of buffers in use at any one time.In a normal system with only a few permanently allocated buffers, something like 2 kilobytes is a reasonable pool size. In a large system, 4-6 kilobytes may be more appropriate.
6.7.2.2 Memory Required By Stacks
Each prioritized and background process must have its own stack. The stack will contain return addresses, local variables and any data that the process may push. The stack must be large enough to contain all data needed at any one time.When an interrupt occurs the interrupt process must have a stack to use during the interrupt. OSE Epsilon for ARM maintains one stack shared by timer-interrupt and interrupt processes. Stack requirements of these processes do not affect the size of the stacks reserved for prioritized and background processes.A process written in C typically requires 160-256 bytes of stack. However, this depends largely on the application. A few C library functions need a lot of stack, maybe 1-2 kilobyte. If a process requires large dynamic arrays or strings it may also need more stack. A reasonable approach is to start with 256 bytes and adjust stacksizes after a while when actual demands can be seen.
AR
M K
erne
l
100 • Memory Requirements User’s Guide / 4.6
6.7.2.3 Memory requirements
Memory requirements are listed in the following tables:
Add stacks, pool size and the amount of memory used by the operating system to find out total data memory needs.Note: There is a 72 byte register save area as well (80 byte for XSCALE).
Table 1: RAM requirement for OSE Epsilon for ARM
mode: normal single chip
kernel 376 220
per process, PCB 68 52
per process,
minimum stack 160 160
Signal header 12 8
AR
M K
erne
l
User’s Guide / 4.6 Memory Requirements • 101
2
2
.
The amount of code memory required is mainly determined by the size of the application programs. Only if the system is very small the size of the operating system is importantIn the minimum configuration, only the system calls alloc, send, receive, free_buf and delay are used.eldm is the debug monitor which is needed if the OSE Illuminator system level debugger will be used.
Table 2: ROM requirements for OSE Epsilon for ARM
RTOS memory required
Kernel (minimum, no debug) 2.0 kbytes
Kernel (full, no debug) 4.0 kbytes
Kernel (minimum, debug) 2.5 kbytes
Kernel (full, debug) 4.5 kbytes
Kernel (minimum, debug + eldm) 7.5 kbytes
Kernel (full, debug + eldm) 9.0 kbytes
AR
M K
erne
l
102 • Speed Considerations User’s Guide / 4.6
6.8 Speed ConsiderationsWhen designing a system, it is often necessary to decide if it meets certain speed requirements. This section is intended to provide some help when calculating speed. All execution times are approximate, remember that times extend due to interrupts etc. The conditions for execution times are the same as in section 7.Generally, if a system is not fast enough with OSE, it will certainly not be fast enough without. There are two reasons for this:
1. Systems running under OSE are always executing at the code section which is most important at any particular moment.
2. The task of directing the work must be done, either by the operating system or by user code. Since the executive is written in assembly and much work has been spent optimizing it, it is mostly faster than user code.
The execution times stated in this paragraph assume a ARM7TDMI processor running with a clock frequency of 64 MHz (OSE Epsilon for ARM in RAM, one wait state), and that the system has been configured for fast execution with no debug options selected.
6.8.1 Task Switch PerformanceThe time required for a task switch is determined by system configuration. In an OSE Epsilon for ARM system, the task switching time is 2 microseconds.
6.8.2 Timer-Interrupt Process FrequencyThe maximum frequency which might be used for timer-interrupt processes is determined by the system tick. The tasks to be performed at each system tick must be finished before the next tick. 2 us are always required for a tick. If at least two background processes are used, add another 1 us. For each delay or timeout which expires during a tick, add another 3 us. For each declared timer-interrupt process, add 2 us of operating system overhead. Each timer-interrupt process activated requires another 4 us in addition to the time used by the process itself.Add the times for a worst case situation in your system and you will see the maximum timer-interrupt frequency. Keep in mind that if timer-interrupts use up all time between ticks, other parts of the system will be unable to execute.It is not reasonable to expect to activate a timer-interrupt process more often than every 500 us, even if the system has been designed with this purpose in mind.
AR
M K
erne
l
User’s Guide / 4.6 Signal Transmission Performance • 103
2
2
6.8.3 Signal Transmission PerformanceA complete signal transmission sequence would be:
1. allocate a buffer,
2. send the signal,
3. change to the receiving process,
4. receive the signal,
5. free the buffer.
This whole sequence would at least use up approximately 13 us.If a shorter time is required, use the same buffer back and forth between the processes. This would reduce the time consumption to 8 us.The time between an interrupt process is activated and in its turn has activated a prioritized process would be 13 us.
6.8.4 Interrupt Handling PerformanceInterrupts are usually used to provide fast response. The time from hardware signals an interrupt until execution of the first line of code dealing with the interrupt is often referred to as interrupt latency.Two components determine interrupt latency:
1. The time required to initialize the interrupt. The state before the interrupt must be saved and execution must be transferred to the interrupt handling routine.
2. Interrupts are disabled from time to time. This is done by the CPU itself, by OSE and by user programs. OSE disables interrupts for a maximum duration of us. The time under (1) above must be added to the time interrupts may be disabled.
6.8.5 Time Consumption of Other FunctionsFunctions other than interrupts, task switches, ALLOC, FREE_BUF, SEND and RECEIVE have not been considered as time critical. The execution times for DELAY and RECEIVE_W_TMO vary widely, depending on number of pending delays and timeouts in use, interrupts disturbing etc.The system start always consumes time to initialize all tables and variables. If no users start handler is present a medium sized system configured no debug requires approximately 700 us to start.
AR
M K
erne
l
104 • System Start User’s Guide / 4.6
6.9 System StartWhen the system is started, it starts execution at the symbol START_OSE in osarm.*.Interrupts are disabled.The system then initialises a small temporary stack and calls the power on handler if present. If a warm start is required, control is immediately passed to the process which was running when POWER_FAIL last occurred. If no warm start is required, the users start handlers, if any, are called one at a time. Start handlers get a slightly larger stack. When start handlers are called, no memory has yet been initialised. The current stack is located in memory between the symbols ZZ_TEMP_STACK_E (low limit) and ZZ_TEMP_STACK (high limit).When the start test is done, OSE Epsilon for ARM initialises its internal data structures.The prioritized process with the highest priority is swapped in and allowed to start executing from the first instruction. Other processes are activated as required by priorities and events. Background processes start executing when no prioritized process is ready.
6.10Writing the Interrupt HandlerIn OSE Epsilon for ARM, you have to supply a user-written Interrupt Handler to be able to use OSE Interrupt Processes.
6.10.1 Sample Interrupt HandlerThe OSE Epsilon for ARM delivery (Board Support Packages, bsp) contains templates which describe how to write your own interrupt handler (i.e. c:\ose\epsilon\arm\krn\<compiler>\bsp\<board_type>\inthdlr.s). When interrupt, the user has to decide which interrupt occurred and call proper interrupt process. One interrupt source must call the OSE_TIMER_ENTRY to manage system tick.
6.10.2 Nested OSE InterruptsIf nested interrupts are required, macros INIT_INT_NESTED and QUIT_INT NESTED must be used.When the first interrupt occurs all registers are saved in the data area of running process. When a nested interrupt occurs, registers must be saved on the interrupt stack. INIT_INT_NESTED does all this and switches the CPU mode to SYSTEM mode. Before re-enabling interrupt, user may set a new interrupt mask in order to mask out interrupts with the same or lower priority.When leaving a nested interrupt, register values are restored from the interrupt stack. When leaving, lowest level of interrupt registers are restored from the data area of the running process. The dispatch request flag (DP_REQ) is also checked, to determine if a dispatch is required. QUIT_INT_NESTED does this.
AR
M K
erne
l
User’s Guide / 4.6 Interrupt Enable/Disable Functions • 105
2
2
6.10.3 Interrupt Enable/Disable FunctionsSince OSE Epsilon for ARM runs most of the time in Thumb- and System-Mode, there is no normal way to disable interrupts. Therefore the user must provide three functions which can be found in the file inthdlr.s in the delivery bsp directory (c:\ose\epsilon\arm\krnxxx\<compiler>\bsp\<board>\src\inthdlr.s):
1. arm_lock. This function should lock interrupts in the interrupt-controller and save the current status on the stack. This function is called from Thumb-mode.
2. arm_unlock. This function should restore the interrupt controller status with a value read from the stack. This function is called from Thumb-mode.
3. zz_interrupt_enable_a. This function should enable all interrupts in the interrupt controller from a value stored in a shadow register. It is called from ARM-mode.It is called only once at system startup right before the first process is swapped in.
AR
M K
erne
l
106 • Writing a Link Handler User’s Guide / 4.6
6.11 Writing a Link HandlerThis section is not intended to be a complete instruction on how to write a link handler. You will probably need extensive knowledge on communications software before writing a good link handler. The following text will merely try to explain matters particular to OSE.Processes in every CPU running OSE are numbered from 1 up to the number of processes. These numbers are also the addresses of the processes. When a signal is sent to an external CPU the addressee will be stated as a number, higher than process number 255 in the sending CPU.When SEND finds an addressee higher than 255 in the CPU, that signal will be forwarded to the link handler of the CPU. The link handler must have a table with information which enables it to translate addresses used in its CPU to addresses valid in the receiving CPU.Apart from the address translation task, a link handler must contain communication software for the type of link used. How to write that software is outside the scope of this manual.A link handler is an ordinary prioritized process with the process name LINKHANDLER (must be in capitals). No other name may be used. Other processes may send signals to the link handler in the same way all signals are sent. In addition to that, all signals sent to processes unknown to SEND will generate an OSE system error.Ordinary signal buffers contain no information about the addressee, since the process which received the signal is the addressee. Signals sent to processes outside the CPU have a different format containing the address of the process to which the signal is to be sent. The link handler should use the ADDRESSEE system call to look at the address of the buffer and decide if that address is valid. If the address is not recognized, the link handler should call ERROR.Signals, coming from processes in other CPUs, can be received by the link handler or some other process. A process receiving signals from a physical link allocates a signal buffer using ALLOC, places the received signal in the buffer and sends it to the addressee inside this CPU.The SEND_W_S system call is used for this purpose since it enters a specified process as sender of the signal. This allows the link handler to emulate the global sender of the signal.
AR
M K
erne
l
User’s Guide / 4.6 Multiple Physical Links • 107
2
2
6.11.1 Multiple Physical LinksIf there are many physical links in the system, you are likely to need one link handler for every physical link. Only one link handler may be named LINKHANDLER and receive signals from SEND however.That link handler will have to forward signals to other link handlers using the SEND_W_S call as necessary.Those signals should not be restored and freed until they have reached the leaf link handler.
6.11.2 Buffer StructureBuffers sent by SEND to the link handler have the following structure:Buffer size in bytes is counted from signal number to the last byte. I.e. a buffer containing only the signal number will have buffer size set to 2.The system calls ADDRESSEE, SIGSIZE and SENDER may be used to extract information from the buffer structure in a portable way.
6.11.3 Reformatting BuffersThe buffers received from RECEIVE directed to an external process have a different format than ordinary buffers. The format of ordinary buffers is described in the section on the system call ALLOC, the special format was detailed in the section above. NOTE that the special format is applicable only to signals directed to external processes. Signals sent from a process directly to the link handler are of standard format.Special format buffers must be reformatted before they can be returned to the system. This is done by the system call RESTORE. (For details, see System Calls.)
AR
M K
erne
l
108 • Writing an Error Handler User’s Guide / 4.6
6.12Writing an Error HandlerWhen an error has been detected, it is often desirable to log the error and additional data on some logging device or a display. Since the operating system can not know which devices are available in a particular system the operating system remains in an infinite loop after an error. If other actions are to be taken, the user must write an error handler to do this work. Interrupts are disabled while the error handler is executing.You are not allowed to use system calls in the error handler except: ADDRESSEE, CURRENT_PROCESS, GET_FSEM, GET_PRI, GET_TICKS, SENDER, SIGSIZE, WAKE_UPNOTE that the name of the error handler must be declared in the configuration file osarm.con.Error handlers may be written in C or assembly.
6.12.1 Error InformationWhen the users error handler is called, information on the error is available in the global ERR_MSG array and in the CPU-registers. In order to obtain the information the ERR_MSG array must be declared as an external variable:Syntax: extern unsigned int ERR_MSG[5];
EXAMPLEextern unsigned int ERR_MSG[5];
display( ERR_MSG[1] ; /* Display running process, *//* assuming you have written *//* a procedure display to *//* show the digits. */
The following five integers of information are provided:
• ERR_MSG[0]Error number. (For details, see Run-Time Error Messages.)
• ERR_MSG[1]The process which was running when the error occurred. Processes are numbered from 1 which is assigned to the first process declared in osarm.con and increased by one for each subsequent process.
• ERR_MSG[2]The address of the process control block (PCB) of the running process.
• ERR_MSG[3]Current stackpointer.
• ERR_MSG[4]Zero when called from user.
AR
M K
erne
l
User’s Guide / 4.6 Error Information • 109
2
2
If the operating system itself detected the error, ERR_MSG[2] will be non zero. If this occurs ERR_MSG[0] - ERR_MSG[4] have the following functions:
• ERR_MSG[0]Error number. (For details, see Run-Time Error Messages.)
• ERR_MSG[1]The process which was running when the error occurred. Processes are numbered from 1 which is assigned to the first process declared in osarm.con and increased by one for each subsequent process.
• ERR_MSG[2]The address of the process control block (PCB) of the running process.
• ERR_MSG[3]Current stackpointer.
• ERR_MSG[4]Non zero when called from user.
AR
M K
erne
l
110 • Continuing After an Error User’s Guide / 4.6
6.12.2 Continuing After an ErrorIt is not possible to continue when the operating system has detected an error.If a user process has detected an error, the error handler may decide to continue execution, perhaps after the error handler has restored the situation.If the user-written error handler decides to continue, it may return to ERROR where execution will continue after the statement where ERROR was called. If the user-written error handler decides not to continue, it must remain in an infinite loop.If the user-written error handler decides to restart the system, it must enforce a reset of the CPU.
AR
M K
erne
l
User’s Guide / 4.6 Illuminator Debugger • 111
2
2
7 Illuminator DebuggerIlluminator is a System Level Debugger for the OSE Real-Time Operating System from Enea Embedded Technology. Illuminator can be used for OSE (aka OSE Delta), OSEck (aka OSE for DSP) and OSE Epsilon systems.OSE Illuminator is delivered on a separate OSE Delta CD (labelled OSE X.X, where X.X represents the version). In a typical real-time system, the crucial parts are the interfaces between the different system components and the real-time behaviour and status of system functions and resources. In an OSE system, the components are processes and the interface is always made up of OSE signals. With a traditional source code debugger, it would be a tough job to supervise or debug these interfaces because a source level debugger concentrates on code lines. Our OSE Illuminator system level debugger is designed to make it easy to work with the signal interfaces.Illuminator is a standalone debugger which will be used together with a serial line or other interfaces for target connection. It can therefore be used together with any other debugging tool such as Emulators and ROM-Monitor-HLL-Debuggers from any supplier.The OSE Illuminator System Level Debugger can be connected in different ways to an OSE Epsilon target system. Illuminator consists of a user interface and a communication module called Epsilon Debug Server (edbgserver.exe) on the host, and the ARM Debug Kernel on the target.Please consult the “Illuminator User’s Guide” for a detailed description of OSE Illuminator. You can find this manual in the OSE Delta delivery.
AR
M K
erne
l
112 • Serial Line Connection User’s Guide / 4.6
7.1 Serial Line Connection
Illuminator is connected to the Epsilon Debug Server (edbgserver) over a host TCP/IP connection.The debug server translates the Illuminator signals into a special debug protocol which is send over the serial line to the target system.The ARM Debug Kernel contains the target system level debug functions. It is connected over a serial driver (serial.c) to the serial line connection to the host system.By means of different hooks into the OSE kernel the debug module gets all necessary system information from the kernel.As all debug functions are located in the target the Debug Kernel functions need some target resources. The hooks into the kernel results in some timing overhead when debug is enabled. The debug functions also uses code and data memory from the target system. All event trace is performed in the target.The ARM Debug Kernel will automatically be generated if the debug option (DEBUG YES) is selected in the OSE Epsilon for ARM configuration file osarm.con.You also need a communication module to connect the ARM Debug Kernel to the host. For an asynchronous serial line connection the driver serial is included.
Figure 7.1 Serial line connection between host and ARM target
Illuminator
edbgserver
ARM
serial
Serial Line
Host Target
comx uart
TCP/IP
Debug Kernel
AR
M K
erne
l
User’s Guide / 4.6 System Configuration • 113
2
2
7.1.1 System ConfigurationAs you are already familiar with the OSE Epsilon for ARM real-time operating system, you know that you are configuring the system with the configuration file osarm.con. There are three entries in this file for debugging:; 2.1 Debug options (must not be left empty);; DEBUG (YES | NO); BUFFER_CHECK (YES | NO); STACK_CHECK(YES | NO); OPTION DEBUGGER,(NO | ONCHIP,<trace>, <evact>
DEBUG YESBUFFER_CHECK YESSTACK_CHECK YESOPTION DEBUGGER,ONCHIP, 1024, 16
The entries for DEBUG, BUFFER_CHECK and STACK_CHECK must not be left empty and you can switch on these run-time functions also without using OSE Epsilon Illuminator. A Buffercheck or Stackcheck error will then jump into an errorhandler if you have defined one.The OPTION DEBUGGER must not be left empty. The OPTION DEBUGGER, ONCHIP will enable some hooks in the OSE Epsilon for ARM kernel and generate the OSE Epsilon for ARM Debug Kernel.After the system configuration file osarm.con is satisfactory run the configurations utility confarm.exe. Confarm.exe reads the configuration file osarm.con and produces the configured kernel. Assemble this file and link it together with your system. You will find the confarm.exe in the ..\conf\ directory of your OSE Epsilon for ARM installation.
AR
M K
erne
l
114 • Testing the Target Debug Connection User’s Guide / 4.6
7.1.2 Testing the Target Debug ConnectionAfter you have downloaded the generated application into the target system and started the target you can check the host-target communication by a simple test.
1. Download the application including the ARM Debug Kernel and serial driver into the target.
2. Start the target system from your system level debugger.
3. Connect the serial line cable for the Illuminator debugger.
4. Open a suitable terminal program on the host PC.
5. Be sure that you have selected the right communication port and the right baud rate (same as in serial of the target) on your host PC.
6. Enter the command VE in the terminal.
7. The target system should now respond with:
>OSE Epsilon for ARM ver. X.Y.Z>ELDM for ARM ver. X.Y.Z
If the target system is not responding you need to debug the target modules and to check the communication settings.
AR
M K
erne
l
User’s Guide / 4.6 Epsilon Debug Server • 115
2
2
7.1.3 Epsilon Debug ServerIf the targets system is running, you have to start a small communication program on the host system called edbgserver manually.If you have installed OSE Epsilon for ARM at the default location on your PC, you can find the edbgserver.exe file in the directory:c:\ose\epsilon\arm\krnxxx\binIlluminator communicates with the Epsilon Debug Server (edbgserver.exe) which controls the Serial Interface of the PC. Please note that the Illuminator uses TCP/IP, so make sure that networking is enabled on your machine (you can verify this by using the ping command, e.g. “ping myhost” where myhost is the host name of your PC).Open a MS-DOS shell window and change the working director of this windows to the directory where edbgserver.exe is located. Run edbgserver.exe.You will see now the following window:
edbgserver communicates by default over COM1 with a baudrate of 115200 baud. If you need another baudrate or another serial interface, type edbgserver in the command window with the following parameters:edbgserver <com=x> <bd=y> <silent> <debug>
where:
• <com=x> is the comportx = 1, 2, 3 or 4. Default value is 1.
• <bd=y> is the baudrateyy = 9600, 19200, 38400, 57600 or 115200. Default value is 115200.
• <silent>The silent option will remove the “system alive” prompt (swimming fish) from the edbgserver window. This allows user debug messages from the target to be displayed in the edbgserver window.
AR
M K
erne
l
116 • Symbolic Signal Information User’s Guide / 4.6
• <debug>If the debug option is selected, you can see the eldm low level debug commands. All eldm debug messages from the target are displayed, e.g.:
edbgserver com=2 bd=38400edbgserver com=2 silent debug
7.2 Symbolic Signal InformationDue to some limitations, Illuminator cannot load symbolic signal information generated by the ARM, GNU and IAR tool chain. Therefore, Symbolic Signal Information for OSE Epsilon for ARM target systems is not available in this version.
AR
M K
erne
l
User’s Guide / 4.6 Timeout Server • 117
2
2
8 Timeout ServerThe Time-Out Server allows processes to handle time intervals either to schedule events or to detect time-out conditions.Include the following entry in osarm.con:TI_PROC tosv,<timeslice>
The time resolution is <timeslice> * system clock ticks.The Time-Out Server is delivered in source code. The file name is tosv.c and can be found in SRC directory of the OSE installation.The functions are described in:• “Request Timeout” on page 118
• “Cancel Timeout” on page 119
• “Retrigger Timeout” on page 119
AR
M K
erne
l
118 • Request Timeout User’s Guide / 4.6
8.1 Request TimeouttimeoutID cancel = request_tmo(S32 time, SIGSELECT signal_id);request_tmo let user processes request time out signal after a specific time interval with a resolution down to clock ticks. The signal ID of the received signal after a time-out is the signal ID specified in the request_tmo system call. The request_tmo returns cancel information which can be used if user process wants to cancel the time out.If time is positive, it is taken relative to the current system time. If it is negative it is the absolute represented system tick at which a timeout should occur.Returns an ID which can be used to remove the timeout with cancel_tmo.Example:request_tmo(-10000,0x1234);
get Signal 0x1234 at tick 10000
request_tmo( 10000,0x1234);
get Signal 0x1234 at tick + 10000
AR
M K
erne
l
User’s Guide / 4.6 Cancel Timeout • 119
2
2
8.2 Cancel Timeoutvoid cancel_tmo (timeoutID cancel_info);Removes a timeout-request. The given ID is checked and if valid, the timeout-request is removed from the list.Example:timeoutID cancel_info;cancel_info = request_tmo(100L,3);/* A signal with identity 3 is returned after *//* 100 systemticks cancel_info holds information *//* if the time-out must be cancelled */void cancel_tmo(timeoutID cancel_info)
User process can cancel their own previously given time-out request by calling cancel_tmo. Do not use the same signal ID at the same time when using cancel_tmo.
8.3 Retrigger Timeoutvoid retrigger_tmo (S32 new_time, timeoutID id);Set a timeout value to a new time. If the timeout had occurred before retrigger_tmo is called, an error will be generated.Example:retrigger_tmo (-10000,last_tmo);
AR
M K
erne
l
120 • Retrigger Timeout User’s Guide / 4.6
AR
M K
erne
l
User’s Guide / 4.6 Glossary • 121
2
2
9 GlossaryMany of the terms used in this manual are specific to operating systems and real-time systems. These can have a different meaning in different contexts. Below, you will find definitions of terms as they are used in this manual.
as shipped The OSE-files as they were delivered to your company.
buffer A section of memory. It is reserved using the ALLOC system call. It is often used to store signals.
buffer pool The section of memory containing all reserved buffers. At times there is memory left in the pool where more buffers may be re-served.
code The instructions which make up a program.
code memory The memory where code constants are stored. It is often ROM or PROM but can also be RAM in an emulator or target system.
communication System call designed specifically for communications software.
function In OSE, FLUSH, RESTORE, ADDRESSEE and SEND_W_S are communication functions.
concurrent Events which occur at the same time. For example, in a terminal, the operator may type at the keyboard and the host computer may send characters concurrently.
configuration The operating system may contain different parts of code and be-have differently depending on the configuration. The configuration is determined by data entered by the designer into the ostri.con configuration file.
debugging Locating end removing errors from a system.
development The tools used to develop a system.
tools For example: editors to write source code, assemblers/compilers to generate machine readable instructions, emulators to find errors.
dispatch To decide which process is to run at a particular moment. The ready process which has the highest priority is always selected.
See also: swap, task switch.
dispatcher The program which performs a dispatch.
AR
M K
erne
l
122 • Glossary User’s Guide / 4.6
emulator A tool to locate errors. With an emulator you may look inside the CPU to see where in the code it is executing, the value of variables etc. An emulator can also stop execution at interesting points in the program. An emulator is necessary to be able to use the full power of the OSE system level debugger.
event Something happens in the system. For example, the operator may have pressed a button. Events are often connected to interrupts or polled.
execute To issue instructions to the CPU. The instructions are then carried out by the CPU.
hang The program system has experienced a deadlock. It will cease to function and the system will appear to be dead to an observer.
interface The boundary between processes. Together, all contacts between two processes is their interface. In OSE, the process interface con-sists of the signals exchanged between the processes.
interrupt An event which, through hardware, causes the CPU to transfer con-trol from the currently running program to another program called interrupt process. For example, as soon as a bit changes the CPU starts executing a subroutine which handles that event. No time is spent checking whether the bit has changed or not.
See also: poll.
interrupt latency The time from the occurrence of an event until the first instruction of the corresponding interrupt process is executed.
interrupt source The hardware which causes an interrupt. For example, a timer or a pin on the CPU.
memory pool See buffer pool.
message See signal.
not ready When a process has no further work to do it becomes not ready. It will then be swapped out by the operating system.
See also: ready (p. 123).
operating system The part of a program system which decides which processes to run, and when. It also distributes the resources of a system, such as memory and time. OSE is an operating system.
process A process is a program which runs independently of other pro-grams. In principle, a process may act as if it was alone in the CPU.
AR
M K
erne
l
User’s Guide / 4.6 Glossary • 123
2
2
pointer A word (2 bytes) of memory containing an address to another part of memory. A pointer may, for example, point to a buffer, i. e. con-tain the address to a buffer.
poll To check for an event at regular or irregular intervals. For example checking the value of a bit every millisecond. If the bit has changed, a subroutine is executed to handle that event. After the bit has changed, there may be some time before it is checked and the subroutine is started. The CPU always spends a fraction of its time checking the bit, and perhaps other bits.
See also: interrupt (p. 122).
pool See buffer pool (p. 121).
ready As soon as a process has something to do it becomes ready. If it has higher priority than the process currently running the currently run-ning process is swapped out. A process may be ready for a long time without being permitted to execute.
See also: not ready (p. 122).
real-time An administrative program, for example a word processor, may keep its user waiting for long intervals of time. It will still not be considered useless. A program controlling the brakes of a car will not be very useful if it needs a minute to calculate what to do when the brake pedal is pressed. Programs which have to react to exter-nal events within a limited time are called real-time programs. An operating system designed to handle such programs is a real-time operating system.
re-entrant Code is re-entrant if more than one process at a time may execute it. This requires that the code does not use fixed variable locations i. e. it must use registers or the stack. The OSE system calls are re-entrant. Code which is not re-entrant can not be called from more than one process unless interrupts are disabled.
For example, consider the following C-procedure:
my_proc()
{
extern int my_variable;
my_variable += 1;
}
This code is not re-entrant.
AR
M K
erne
l
124 • Glossary User’s Guide / 4.6
Assume that my_variable has the value 17. If process A calls my_proc, the procedure reads my_variable and finds 17. Then process A is swapped out for some reason and process B is swapped in. After a while process B calls my_proc and my_proc increments my_variable which then becomes 18.
A moment later process B is swapped out and process A is swapped in again. It has already read my_variable which was then 17 and now increments it to be 18.
Result: my_variable is still 18 although it has been incremented twice since it was 17!
run See execute (p. 122).
signal A buffer which is sent from one process to another.
swap To save the environment of one process and then restore the envi-ronment of another process.
system Together, all hardware and software of your product form the sys-tem which you design.
system call The processes may call the operating system when they want to use its services, for example sending or receiving a signal. Such calls are referred to as system calls. System calls are the only way for processes to obtain service from the operating system.
system crash The program system executes out of control. The behaviour of the system can not be predicted in case of a system crash. A system crash is the result of errors in user processes or it may result from electrical upsets. Almost every system crash is detected by the er-ror locating devices of the operating system.
system Is the act of entering configuration data into the configuration
generation file and assembling the operating system.
system tick At regular intervals, the operating system checks to see if delays or timeouts have run out or if a timer-interrupt process should be ac-tivated. These intervals are called system ticks.
target system The hardware where your programs will ultimately run.
task Work to be performed by some part of some program.
task switch To swap out a process, perform a dispatch and swap in a new proc-ess.
See also: dispatch (p. 121), swap (p. 124).
AR
M K
erne
l
User’s Guide / 4.6 Glossary • 125
2
2
user Someone using the operating system.
user interface The system calls programmers use when they communicate with the operating system.
AR
M K
erne
l
126 • Glossary User’s Guide / 4.6
User’s Guide / 4.6 Index • 127
AR
M K
erne
lIndex
AARM 45Assembly-Time Errors 80
BBackground Process 74, 86baudrate 115Buffer Check Option 50Buffer Sizes 56Buffer Structure 107Buffer Transfer 96BUFFER_CHECK 113Building a System 77
CC Compiler 45Cancel Timeout 119comport 115COND_HALT_W_TIMINT 53Configuration 79configuration
background processes 74buffer 50buffer sizes 56C compiler 45check 51conditional halt 53CPU types 47debug option 49enable wake_up 75error handler 59Idle Handler 68interrupt processes 70interrupt stack 57Link Handler processes 73option debugger 52OSE dispatcher 54power off handler 65power on handler 64prioritized processes 72receive handler 63send handler 62start handler 60swap handler 61target name 46temporary stack 58
Configuration file 43Configuring 43Continuing After an Error 110CPU 11CPU Type 47
DDEBUG 113Debug Kernel 40, 77, 79, 111, 113Debug Option 49Definition of Terms 121Dispatcher 12DISPATCHER_IN_RAM 54
Eedbgserver 40, 42, 112, 115Enable Wake Up 75Epsilon Debug Server 40, 42, 111, 112, 115ERR_MSG 108Error Handler 59Error Information 108Execution time 102
FFast Semaphore 22, 97FLUSH 97
GGET_FSEM 97Getting Started 25GHS 45Global Variables 98
HHardware 11
IIAR 45Illuminator 40, 42, 79, 111Interprocess Communication 11Interrupt Handling Performance 103Interrupt latency 103Interrupt Performance 18Interrupt Process 17, 70, 87Interrupt response time 18Interrupt Stack 57
Lled.c 34led.h 34LEDs 34Link Handler Processes 73
MMailbox 20
User’s Guide / 4.6 Index • 128
AR
M K
erne
lmax. evact 52max. trace 52Memory Model 48Memory Required By OSE for ARM 100Memory Required By Stacks 99Memory Requirements 99Memory Used By the Buffer Pool 99Memory Utilisation 98Message 20, 22, 94Multiple Physical Links 107
NNested interrupts 57
OONCHIP 52, 113Option Conditional Halt 53OPTION DEBUGGER 113Option Debugger 52Option Dispatcher in RAM 54osarm.con 30, 43, 79osarm.s 77OSE 4.2 111
PPool Size 55Power On Handler 64Pre-emptive 13Prioritized Process 17, 72Priority Based Process Scheduling 14Process 9, 11, 81, 83Process States 13
RRAM requirement 100READY 13Receive Handler 63Reformatting Buffers 107Request Timeout 118Resource 11Resource Management 11RESTORE 96Retrigger Timeout 119ROM requirements 101Round-Robin Process Scheduling 14RUNNING 13
SSemaphore 23Semaphores 97Send Handler 62serial 112
Serial Line Connection 112serial line Illuminator system 41SET_FSEM 97Signal 9, 81, 94Signal transmission sequence 103SIGNAL_FSEM 23, 97SINGLECHIP 45Speed 12, 81Speed Considerations 102Stack Check Option 51STACK_CHECK 113Start Handler 60Starting and Stopping Processes 93Static Process 16Swap Handler 61Symbolic Signal Information 116System Configuration 113System Creation Cycle 83System Design 81System Initialization 79System Start 104system2.h 34
TTarget Name 46Temporary Stack 58Terminal 114Testing the Target Debug Connection 114Time Management 11Timeout Server 117Timer Interrupt Process 19, 71
UUNIX 14Using Signals In Processes 95
WWAIT_FSEM 23, 97WAITING 13Writing a Link Handler 106Writing an Error Handler 108Writing the Interrupt Handler 104