enea ose epsilon for arm release notes

AR

M K

erne

l

Reference Manual / 4.6 1

2

3

OSE Epsilon

ARM Kernel

Reference Manual

AR

M K

erne

l

2 Reference Manual / 4.6

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.

AR

M K

erne

l

Reference Manual / 4.6 Contents 3

2

3

Contents1 Introduction 5

2 System Call Summary 7

3 System Calls 113.1 Data Type Definitions 123.2 Basic System Calls 133.3 Advanced System Calls 133.4 System Calls for Link handler 143.5 System Calls for Semaphores 143.6 System Calls for Fast Semaphores 143.7 System Calls 15

4 Timing Specification 61

5 User Interface 655.1 Header and Include Files 665.2 Data Types 67

6 Error Messages 696.1 Run-Time Error Messages 706.2 Configuration Error Messages 76

7 Reserved Words 79

AR

M K

erne

l

4 Contents Reference Manual / 4.6

AR

M K

erne

l

Reference Manual / 4.6 Introduction 5

2

3

1 IntroductionOSE Epsilon for ARM is a fast, compact, real-time operating system for the ARM (Thumb) line of microprocessors from ARM Ltd.The purpose of this Reference Manual is to give the reader a good understanding of the different mechanisms in OSE. It contains also the system call summary, a detailed description of every system call, specification of data types and an error message guide.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 contains reference information for ARM Kernel, described in:

System Call Summary on page 7 gives a system call summary.

System Calls on page 11 is a detailed description of every system call in C.

Timing Specification on page 61 indicates the timing of all system calls

User Interface on page 65 defines the user interface with header files and data types.

Error Messages on page 69is the Error Message Guide for run-time and configuration error messages.

Reserved Words on page 79 is a description of reserved words.

Document Revisions on page 83 is the document revision history.

AR

M K

erne

l

6 Introduction Reference Manual / 4.6

AR

M K

erne

l

Reference Manual / 4.6 System Call Summary 7

2

3

2 System Call SummaryThis chapter contains the OSE system call interface, i.e. all the available system calls, manifest constants and macros. A brief explanation is given of every call.

Table 1: System calls for the ARM Kernel

System call Description

(p. 15) ADD_TICKS adds a specified number of ticks to the system tick counter.

addressee (p. 16) ADDRESSEE finds addressee of signal directed to process in another CPU.

alloc (p. 18) ALLOC reserves memory for a user process.

alloc_nil (p. 20) ALLOC_NIL reserves memory for a user process. ALLOC_NIL works like ALLOC with the exception that memory shortage causes return of a NIL pointer.

cond_halt (p. 21) COND_HALT conditionally calls the power off handler, depending on the number of ticks remaining before the next scheduled time-out event.

create_sem (p. 22) CREATE_SEM creates a dynamic semaphore structure.

current_process (p. 23) CURRENT_PROCESS returns the process ID of the cur-rently running process.

delay (p. 24) DELAY suspends execution of the calling process for the requested number of system ticks.

error (p. 25) ERROR collects error information and is called by any user process detecting an error condition.

flush (p. 26) FLUSH removes signals of the requested senders from the signal queue of the designated process.

free_buf (p. 28) FREE_BUF returns memory from a user process to the sys-tem.

get_fsem (p. 29) GET_FSEM reads the current value of a fast semaphore.

get_sem (p. 30) GET_SEM reads the current value of a semaphore.

get_pri (p. 31) GET_PRI returns the current priority level of a prioritized process.

get_ticks (p. 32) GET_TICKS returns current system clock tick count.

AR

M K

erne

l

8 System Call Summary Reference Manual / 4.6

kill_sem (p. 33) KILL_SEM returns a semaphore created by create_sem to the pool.

power_fail (p. 34) POWER_FAIL is used in case of power failure and it causes the present environment to be saved in order to be restored after a warm start.

receive (p. 35) RECEIVE searches the signal queue of the calling process for one or more desired signals.

receive_all_but (p. 37) RECEIVE_ALL_BUT searches the signal queue in the same manner as RECEIVE but with reversed logic. Any signal is received except the signals specified in the array.

receive_fsem (p. 39) RECEIVE_FSEM waits for either a signal, a fast semaphore, or a time-out.

receive_w_tmo (p. 41) RECEIVE_W_TMO searches the signal queue of the calling process for one or more desired signals with a selectable timeout.

restore (p. 43) RESTORE enters the calling process as owner and addressee of the buffer.

send (p. 45) SEND moves a buffer from the sending process to the signal queue of the receiving process.

sender (p. 47) SENDER obtains the process number of the process which sent a buffer.

send_w_s (p. 48) SEND_W_S sends signals exactly like SEND, but the sender of the buffer may be set to any process ID.

set_fsem (p. 50) SET_FSEM assigns a value to a fast semaphore.

set_pri (p. 51) SET_PRI sets a new priority level for the calling process.

signal_fsem (p. 52) SIGNAL_FSEM signals a fast semaphore for the specified process.

signal_sem (p. 53) SIGNAL_SEM increments the value of the specified sema-phore and releases the first process waiting at the semaphore.

sigsize (p. 54) SIGSIZE obtains the size of a buffer.

start (p. 55) START causes a stopped process to resume execution as soon as no process of higher priority is running.



AR

M K

erne

l

Reference Manual / 4.6 System Call Summary 9

2

3For more information, see System Calls on page 11.For a description of the system calls in Assembler, see System Calls in Assembler on page 85.

stop (p. 56) STOP suspends execution of the required process until it is started using the START system call.

wait_fsem (p. 57) WAIT_FSEM waits on a fast semaphore.

wait_sem (p. 58) WAIT_SEM waits at the specified semaphore structure.

wake_up (p. 59) WAKE_UP informs an interrupt process of how it was invoked.



AR

M K

erne

l

10 System Call Summary Reference Manual / 4.6

AR

M K

erne

l

Reference Manual / 4.6 System Calls 11

2

3

3 System CallsSystem calls are calls to the operating system to use its services. This chapter explains how to use system calls by processes written in C. The declarations needed to use the OSE Epsilon for ARM System Calls are present in the header files supplied with OSE Epsilon for ARM, i.e. in the files ose.h and ose_i.h. Only the union SIGNAL declaration must be added.For each call, the syntax of the call is given, followed by an example.The "&"-operator must be used to provide addresses to pointers to buffers. Such pointers are named buf_ptr in the syntax definitions.The C interface protects registers required by the C compiler.System functions can detect user errors. If the Illuminator System Level Debugger is running, it will report such errors. In an actual system, you may wish to write a small error handler procedure to display errors if some display device is available. (For details, refer to the ARM Kernel Users Guide.)Use lower case letters in system call names when calling from processes written in C.See:

Data Type Definitions on page 12

Basic System Calls on page 13

Advanced System Calls on page 13

System Calls for Link handler on page 14

System Calls for Semaphores on page 14

System Calls for Fast Semaphores on page 14

System Calls on page 15

AR

M K

erne

l

12 Data Type Definitions Reference Manual / 4.6

3.1 Data Type DefinitionsThe following datatypes are defined in OSE Epsilon for ARM (defined in the include files ose.h and ose_i.h):union SIGNAL;typedef unsigned short PRIO;typedef unsigned short SIGSELECT;typedef unsigned short PROCESS;typedef unsigned int OSBUFSIZE;typedef unsigned int OSTIME;typedef unsigned int OSTICKS;typedef unsigned int OSERRCODE;typedef short OSSEMVAL;typedef short OSFSEMVAL;typedef char *PDB_LIST;

struct semaphore { OSSEMVAL value;/* Current semaphore value.*/ PROCESS f; PROCESS b; };typedef struct semaphore SEMAPHORE;

The member PROCESS f and PROCESS b are of no interest to applications. Init to NULL.

AR

M K

erne

l

Reference Manual / 4.6 Basic System Calls 13

2

3

3.2 Basic System CallsBasic system calls are present in all OSE systems. They are:

alloc (p. 18)

delay (p. 24)

error (p. 25)

free_buf (p. 28)

receive (p. 35)

receive_w_tmo (p. 41)

send (p. 45)

sender (p. 47)

3.3 Advanced System CallsExtends the basic functionality of the system. Advanced system calls are described in:

(p. 15)

alloc_nil (p. 20)

cond_halt (p. 21)

current_process (p. 23)

get_pri (p. 31)

get_ticks (p. 32)

power_fail (p. 34)

receive_all_but (p. 37)

receive_fsem (p. 39)

set_pri (p. 51)

sigsize (p. 54)

start (p. 55)

stop (p. 56)

wake_up (p. 59)

AR

M K

erne

l

14 System Calls for Link handler Reference Manual / 4.6

3.4 System Calls for Link handlerSystem calls for link handling are described in:

addressee (p. 16)

flush (p. 26)

restore (p. 43)

send_w_s (p. 48)

3.5 System Calls for SemaphoresSystem calls for semaphores are described in:

create_sem (p. 22)

get_sem (p. 30)

kill_sem (p. 33)

signal_sem (p. 53)

wait_sem (p. 58)

3.6 System Calls for Fast SemaphoresSystem calls for fast semaphores are described in:

get_fsem (p. 29)

set_fsem (p. 50)

signal_fsem (p. 52)

wait_fsem (p. 57)

AR

M K

erne

l


2

3

3.7 System Calls

add_ticks

Syntax void add_ticks (OSTICKS ticks);

Description Adds a specified number of ticks to the system tick counter.

Parameters ticks The number of ticks to advance the system tick counter.

Return Value None.

General

add_ticks adds a specified number of ticks to the system tick counter.This system call is intended to make corrections to the system time after the system has been powered down or halted for a while, i.e. in power-on handler at hot start.There are several types of behaviour associated with the system ticks. Only some of these are updated by calling add_ticks. Return value from get_ticks:

Yes, updated

Time when delays and time-outs expire:Yes, updated, if no time-outs are skipped

Timer interrupts:No, not updated

Scheduling of background processes:No, not updated

The other mechanisms will not be updated.If any time-outs or delays were scheduled to expire during the time that was skipped over by calling add_ticks, those delays and time-outs will expire at a later time. This can be avoided by never adding more ticks than the number of ticks indicated by the cond_halt mechanism.

AR

M K

erne

l

16 System Calls Reference Manual / 4.6

addressee

Syntax PROCESS addressee (union SIGNAL **sig);

Description Finds addressee of signal directed to process in another CPU. Addressee examines asignal buffer to find out to which process the buffer was originally sent by the sender.

Parameters sig A pointer to a pointer to a signal buffer.

Return Value The process ID of the addressee of the buffer

GeneralThis system call is intended for link handlers.addressee returns the ID of the process to which the signal was sent.When a signal is sent, OSE tags the buffer with the specified receiver process ID. This is normally the same process that eventually receives the buffer. Therefore addressee returns the ID of the current process most of the time.When a signal is sent to a process which does not exist in this CPU, OSE redirects the signal to a link handler.From this point, the addressee of the buffer is no longer the same as the receiving process, and OSE will not alter the addressee of the buffer until it has been restored with the restore system call.This mechanism enables a link handler to pass the buffer on to other link handler processes using the send_w_s call, without losing the original addressee of the buffer.

AR

M K

erne

l


2

3

Example#include "ose.h"static const SIGSELECT any_sig[] = {0};

union SIGNAL{

SIGSELECT sig_no;};

OS_PROCESS(my_process){

union SIGNAL *sig;PROCESS addr;for(;;){

sig = receive((SIGSELECT *) any_sig);addr = addressee(&sig);if(addr == current_process ()){

/* The signal was sent directly to this process */}else{

/* Signal was sent to another process*/}

}}

AR

M K

erne

l


alloc

Syntax union SIGNAL *alloc (OSBUFSIZE size, SIGSELECT signo);

Description Reserves memory for a user process.

Parameters size The requested size of the buffer.

signo The signal number will be placed in the allocated buffer.

Return Value A pointer to the allocated buffer.

GeneralThis system call is used to reserve memory. The caller must state the amount of memory required and also furnish a value to be inserted in the first halfword of the buffer. The first halfword is used for signal identification when buffers contain signals. It is not illegal to use signal number zero (0) and $8000, but it is not advised, since in the debugger is using these signal numbers. 0 is used to indicate any signal and $8000 is used to signal process swaps. It is an error to try to allocate a buffer of size 0 (zero).

The maximum buffer size is stated in the configuration file (osarm.con). Alloc will select one of the eight fixed memory sizes chosen when the system was generated. The size selected will always be large enough to accommodate the requested number of bytes. Each buffer is preceded by a 12 byte administration block which is used by OSE Epsilon for ARM. Users generally need not care about the administration block.When the system starts, all memory available for buffers is located in the buffer pool. As users allocate buffers, they are removed from the buffer pool and handed over to users. When users return buffers to the system they are stored in lists for returned buffers. They never again return to the buffer pool. If such returned buffers are available, as is almost always the case, alloc will allocate them first.This allocation scheme ensures consistent allocation times and that the memory can never be fragmented, i.e. split up into many small sections, too small to use.If no used buffers of the requested size are available and the system pool does not contain enough memory to allocate the requested buffer, a fatal error is reported. This occurs even if a buffer of a larger size than the closest fit is available.Note that the actual buffer may be larger than requested since the buffersizes are fixed.Process number of the sending process is valid only after the buffer has been sent. Four more bytes are used at the end of the buffer if the debug option is used when configuring the system.

AR

M K

erne

l


2

3

Example#include "ose.h"#define THIRD 3 /* These declarations */struct Third /* are preferably made */{ /* in a .sig-file which*/

SIGSELECT sig_no;/* should be included. */};

union SIGNAL{

SIGSELECT sig_no;struct Third third;

};


union SIGNAL *sig;extern PROCESS proc_;/* Process ID for process "proc" */for(;;){

sig = alloc(sizeof(struct third),THIRD);send(&sig,proc_);delay(100);

}}

AR

M K

erne

l


alloc_nil

Syntax union SIGNAL *alloc_nil (OSBUFSIZE size, SIGSELEC signo);

Description Reserves memory for a user process. alloc_nil works like alloc with the exception thatmemory shortage causes return of a NIL pointer.

Parameters size The requested size of the buffer.

signo The signal number will be placed in the allocated buffer.

Return Value A pointer to the allocated buffer if the alloc_nil call was successful. If there was a mem-ory shortage a NIL pointer will be returned.

GeneralAlloc_nil works like alloc with the exception that memory shortage is treated differently. Alloc_nil returns a NIL pointer in case of memory shortage.Note that designing a system where memory shortage is not a fatal error is much more complicated than designing a system that always expects to have enough memory. It would be necessary to always expect memory shortage when allocating a memory buffer and provide a non fatal alternative action for every instance where memory is allocated. Otherwise memory shortage caused by large memory consumption in one part of the system could cause a fatal failure to allocate memory in another part of the system.Because of these difficulties, using alloc_nil in a system should only be done after careful design analysis. An alternative design approach is often preferable. E.g. if a small portion of the system is expected to consume an undetermined amount of memory, it is probably easier to design a mechanism that limits memory consumption in those areas, than dealing with the system-wide problem of expecting memory shortage.It is however possible to use alloc_nil safely in a limited part of a system if some special conditions are met, by doing 'tricks' with the memory allocation system. The 'trick' is to use alloc_nil only on some of the 8 available buffer sizes, and to create enough buffers of the other sizes at system start. The drawback of this approach is that the flexibility is lost and a thorough analysis of the memory use in the system must be performed.

AR

M K

erne

l


2

3

cond_halt

Syntax void cond_halt (OSTICKS min_ticks);

Description cond_halt conditionally calls the power off handler, depending on the number of ticksremaining before the next scheduled time-out event.

Parameter min_ticks The threshold number of ticks until next time-out event for calling thepower off handler.

Return Value None.

GeneralCond_halt finds out the number of ticks until the next scheduled time-out event. If this is more or equal to the min_ticks value, the power off handler is called.The time-out events considered only include time outs created by the system calls delay, receive_w_tmo and receive_fsem. Other timing related events such as rescheduling of background processes and calling timer interrupt processes do not affect cond_halt.The power off handler is called with information about the number of ticks until the next time-out event. It can use this information to set up a hardware timer for a matching delay time, and then power down or halt the processor. See Configuring OSE Epsilon for ARM, Power off handler for details.The min_ticks value is useful if powering down or halting for very short periods of time should be avoided. That can be the case if the power required to start and stop the system is not negligible. The min_ticks parameter should be set high enough to prevent power down cycles that are shorter than break-even. A min_ticks parameter of 0 will always cause the power off handler to be called.cond_halt is normally called from a background process. This will cause the system to save power when there is no work to be done.Note that the power_down system call is not equivalent to a cond_halt call with a min_ticks parameter of 0. Even though the power off handler will be called in both cases, information about the number of ticks before the next time-out event will only be sent to the handler if called through cond_halt.

AR

M K

erne

l


create_sem

Syntax SEMAPHORE *create_sem (OSSEMVAL init_val);

Description Creates a dynamic semaphore structure and initializes it to the value specified ininitial_val. The initial value must be zero or a positive value. Typical values are 0 and 1.

The semaphore is dynamically allocated from the current pool. It may be returned to thepool when it is no longer in use by calling kill_sem.

Parameters init_val The initial value of the created semaphore.

Return Value A pointer to the created semaphore structure.

General

It is the user's responsibility to ensure that the semaphore is not killed while it is still in use.The semaphore is dynamically allocated from the current pool. It may be returned to the pool when it is no longer in use by calling kill_sem.Semaphores may also be statically defined by simply declaring a static semaphore structure in the program and initializing it. Such semaphores can not be killed.Semaphore structures contain three fields. The first must be initialized to the initial (positive) value of the semaphore. The second and third fields must be initialized to zero, and are required for internal use by the kernel.The three fields of a semaphore structure are named "value", "f" and "b" respectively. The value field is of type OSSEMVAL. The types of the other fields are implementation-specific.This applies only for static semaphores.Example#include "ose.h"


SEMAPHORE *sem;

for(;;){

/* Code */sem = create_sem (1)/* Code */

}}

AR

M K

erne

l


2

3

current_process

Syntax PROCESS current_process (void);

Description The call current_process returns the process ID of the currently running process, i.e. theID of the caller.

Parameter None.

Return Value Returns the process ID of the calling process.

GeneralThis call is used by any process which needs to obtain its own process ID. For example a library function may be interested in from which process it was called.Example#include "ose.h"


PROCESS proc_;

for(;;){

/* Code */proc_ = current_process();/* Code */

}}

AR

M K

erne

l


delay

Syntax void delay (OSTIME time);

Description The call delay suspends execution of the calling process for the requested number ofsystem ticks.

Parameter time The number of system ticks the delay is to last.

Return Value None.

GeneralThis system call is used when a process needs to suspend execution for a time. OSE guarantees that the process is kept waiting for at least the requested time minus one system tick. The actual waiting time may always be longer than the requested, since other processes of higher priority may run for an indeterminate time.Delay can not be called from an interrupt process since an interrupt process can never be swapped out.Example#include "ose.h"


for(;;){

turn_on_lamp(); /* fictive function */delay(10);turn_off_lamp(); /* fictive function */delay(10);

}}

AR

M K

erne

l


2

3

error

Syntax void error (OSERRCODE my_info);

Description collects error information and is called by any user process detecting an error condition.

Parameters my_info The error number to be passed to the error handler.

Return Value None.

GeneralThis system call is used by processes detecting an error condition. The operating system also uses error to report errors.The caller may provide information about the error. It is not necessary to provide information on process number and error location, since this is automatically provided by error.Errors detected by OSE are always fatal and the system can not continue execution; a restart is necessary. The user may provide an error handler to handle detected errors. Such a handler may log the error on a printer, show it on a display, send it on a serial link etc. It will use whatever output devices present in the system. (For details, see 10.9 Writing an Error Handler).If no error handler is present or if an error handler returns from an error detected by OSE, the system enters an infinite loop. If an error handler returns from a user reported error, control is returned to the process calling error.Interrupts are disabled while an error handler is executing.You are not allowed to use system calls in the error handler except:

addressee current_process get_fsem get_sem get_pri get_ticks sender sigsize wake_up

AR

M K

erne

l


flush

Syntax void flush (PROCESS *psel, PROCESS pid);

Description Removes signals from the requested senders from the signal queue of the designatedprocess.

The flush call throws away all signals sent by any of a set of processes specified in psel,from the signal queue of the process specified in pid. The psel parameter is an array ofprocess ID's. The first location contains the number of valid entries in the rest of the ar-ray.

Parameters psel A pointer to an array of processes to flush signals from.

pid The process ID of the receiving process.

Return Value None.

Generalflush is intended for communications software only. The first parameter to flush is a pointer to a RAM array of senders. flush removes every signal from any of the senders from the signal queue of the process in the second parameter. Signals from senders not in the array remain in the queue. The removed signals are freed by flush.The psel array must be built in run-time since process identities are unknown at compile time.The first location in psel contains the number of entries in the rest of the array. Since the PROCESS type may not be compatible to an integer, the count should be cast to the PROCESS type when building psel.Ex: psel[0] = (PROCESS) 1;It is illegal to flush the queue of an interrupt process or timer-interrupt process. It is also illegal to call flush from an interrupt or timer-interrupt process.flush uses start/stop internally to stop processes while their queues are flushed. If flush must be re-entrant (may be called from several processes), the semaphores option is also required.

AR

M K

erne

l


2

3

Example#include "ose.h"

extern PROCESS proc1_;extern PROCESS proc2_;


PROCESS flush_array[2];flush_array[0] = (PROCESS) 1;flush_array[1] = proc1_;for (;;){

/* Code */flush (flush_array, proc2_); /* Throws away all */

/* signals sent *//* from proc1 to proc2*/

/* Code */}

}

AR

M K

erne

l


free_buf

Syntax void free_buf (union SIGNAL **sig);

Description Returns memory from a user process to the system.

Parameters sig A pointer to a pointer to the signal buffer to free.

Return Value None.

Generalfree_buf is used to return memory which is no longer needed. Only memory allocated using alloc may be returned using free_buf. Memory which has been returned can be used by other processes.If you send a signal buffer to another process it is the responsibility of the receiving process to free the buffer. It is an error for the sending process to try to do so.Example#include "ose.h"

static const SIGSELECT any_sig[] = {0};

union SIGNAL{

SIGSELECT sig_no;}


union SIGNAL *sig;for(;;){

/* Code */sig = receive((SIGSELECT *) any_sig);/* Code */free_buf(&sig);

}}

AR

M K

erne

l


2

3

get_fsem

Syntax OSFSEMVAL get_fsem (PROCESS pid);

Description Reads the current value of a fast semaphore.

Parameters pid The ID of the process which owns the desired semaphore.

Return Value Returns the current value of the fast semaphore.

Generalget_fsem is used to read the current value of a fast semaphore.An interrupt process may for example test a semaphore for overflow before calling signal_fsem.Example#include "ose.h"


OSFSEMVAL fsemvalue;for(;;){

/* Code */fsemvalue = get_fsem(current_process());/*Code */

}}

AR

M K

erne

l


get_sem

Syntax OSSEMVAL get_sem (SEMAPHORE *sem);

Description Reads the current value of a semaphore.

Parameters sem A pointer to the specified semaphore

Return Value Returns the current value of the semaphore.

General

get_sem is used to read the current value of a semaphore.

Example

#include "ose.h"

extern SEMAPHORE *sem;


OSSEMVAL semvalue;for(;;){

/* Code */semvalue = get_sem (sem);if(semvalue == 5){

/* Code */}else{

/* Code */}

}}

AR

M K

erne

l


2

3

get_pri

Syntax PRIO get_pri (PROCESS pid);

Description Returns the current priority level of a prioritized process.

Parameters pid The ID of the specified process.

Return Value Returns the priority.

Generalget_pri is used to find out the priority of a prioritized process. The call does not work for any other kind of process.Example#include "ose.h"


PRIO prio;for(;;){

prio = get_pri(current_process());if(prio != 31){

set_pri(++prio);}else{

set_pri(0);}delay(100);

}}

AR

M K

erne

l


get_ticks

Syntax OSTICKS get_ticks (void);

Description Returns current system clock tick count.

Parameters None.

Return value System time in tick.

Generalget_ticks is used to find out the current value of the system clock. The system clock is set to zero at system start. It is subsequently incremented at each system tick.Example#include "ose.h"


long tick;for(;;){

/* Code */tick = get_ticks();/* Code */

}}

AR

M K

erne

l


2

3

kill_sem

Syntax void kill_sem (SEMAPHORE *sem);

Description Returns a semaphore created by create_sem to the pool.

Parameters sem A pointer to the semaphore

Return Value None.

General

Make sure no process is using the semaphore when it is killed.Example#include "ose.h"


SEMAPHORE *sem;for(;;){

/* Code */sem = create_sem(1);/* Code */kill_sem(sem);

}}

AR

M K

erne

l


power_fail

Syntax void power_fail (void);

Description Used in case of power failure and it causes the present environment to be saved in orderto be restored after a warm start.

Parameters None.

Return value None.

GeneralThis call is used in systems where memory contents remain undisturbed in case of temporary power failures. When the power fails, any process may call power_fail.If called from a prioritized or background process, power_fail will swap out the current process and then call the user supplied power off handler to shut down the power source and wait for a restart.If called from an interrupt or timer-interrupt process, power_fail will return immediately to the calling interrupt process. When the interrupt is done, OSE Epsilon for ARM will swap out the current process and then call the user supplied power off handler. The power off handler is declared in osarm.con.When power returns, after reset, the user supplied power on handler is called to determine if memory contents are valid for a warm start or if a cold start is necessary. The power on handler is also declared in osarm.con.If power_fail was called from a prioritized or background process the caller "returns" from power_fail when power is restored and execution may continue where it was interrupted by the power failure.If power_fail was called from interrupt, execution continues at the prioritized or background process which was interrupted by the interrupt which called power_fail.A power off handler may calculate a memory checksum and leave it in memory for the power on handler.A power on handler may recalculate the checksum and allow a warm start if memory remains unharmed. I/O ports must also be initialised to the state that was present when power_fail was called. (This is a major issue which must be carefully considered.)

AR

M K

erne

l


2

3

receive

Syntax union SIGNAL *receive (SIGSELECT *sigsel);

Description Searches the signal queue of the calling process for one or more desired signals. If a de-sired signal is found, it is removed from the queue and handed over to the calling proc-ess.

Parameters sigsel Pointer to an array of the signal numbers to receive.

Return Value Returns a pointer to the received signal buffer. This buffer is owned by the caller fromthat moment.

GeneralReceive will search the signal queue of the calling process for the requested signal(s). The first signal in the queue to match any of the required signals will be received.Sigsel points to an array containing a list of signal numbers to be received.Receive returns to the caller when a signal matching any of the specified signal numbers is found.

The first position in sigsel contains the number of entries in the list that follows. If the number of entries is zero, any signal number is accepted.When called from an interrupt or timer-interrupt process, receive always returns immediately. If no requested signal was immediately available in the signal queue, NIL is returned. This works in a manner similar to receive_w_tmo with a 0 timeout. (Note that receive_w_tmo is not available to interrupt and timer-interrupt processes.)If the signal queue is empty or none of the requested signals is available in the queue the process will be swapped out and another process allowed to run. As more signals arrive, the process will run again in order to scan the queue. Only when one of the required signals has arrived will the process return from the call to receive. A signal in a signal queue will never be scanned more than once during one call to receive.Receive During InterruptIt is permitted for an interrupt or timer-interrupt process to receive signals. If none of the required signals is present in the queue the interrupt process will return from the call to receive and a NIL-pointer is provided.An interrupt process must always be able to handle the case that receive may not return any signal.

AR

M K

erne

l



#define THIRD 3 /* These declarations */struct Third /* are preferably made */{ /* in a .sig-file which*/

SIGSELECT sig_no; /* is included. */};

#define FIFTH 5 /* These declarations */struct Fifth /* are preferably made */{ /* in a .sig-file which*/


union SIGNAL /* A union SIGNAL declaration */{ /* must include a signal */

/* number and the signal */SIGSELECT sig_no; /* structures of the signals */struct Third third;/* that will be used. It must */struct Fifth fifth;/* be present in every */

/* application using signals */};




sig = receive((SIGSELECT *) any_sig);switch(sig->sig_no){

case THIRD:/* Code */

break;case FIFTH:

/* Code */break;default:/* Code */

}free_buf(&sig);

}}

AR

M K

erne

l


2

3

receive_all_but

Syntax union SIGNAL *receive_all_but (SIGSELECT *signotsel);

Description Searches the signal queue in the same manner as receive but with reversed logic. Anysignal is received except the signals specified in the array.

Parameters signotsel Pointer to an array of the signal numbers not to receive.


GeneralReceive will search the signal queue of the calling process for all signal(s) excluding the ones defined in signotsel. The first signal in the queue to match any of the required signals will be received.Sigsel points to an array containing a list of signal numbers to be received.Receive returns to the caller when a signal not matching any of the specified signal numbers is found.The first position in sigsel contains the number of entries in the list that follows. If the number of entries is zero, any signal number is accepted.When called from an interrupt or timer-interrupt process, receive always returns immediately. If no requested signal was immediately available in the signal queue, NIL is returned. This works in a manner similar to receive_w_tmo with a 0 timeout. (Note that receive_w_tmo is not available to interrupt and timer-interrupt processes.)If the signal queue is empty or none of the requested signals is available in the queue the process will be swapped out and another process allowed to run. As more signals arrive, the process will run again in order to scan the queue. Only when one of the required signals has arrived will the process return from the call to receive. A signal in a signal queue will never be scanned more than once during one call to receive.Receive During InterruptIt is permitted for an interrupt or timer-interrupt process to receive signals. If none of the required signals is present in the queue the interrupt process will return from the call to receive and a NIL-pointer is provided.An interrupt process must always be able to handle the case that receive may not return any signal.

AR

M K

erne

l



#define FIRST 1struct First{

SIGSELECT sig_no;};

#define THIRD 3struct Third{

SIGSELECT sig_no;};

union SIGNAL{

SIGSELECT sig_no;struct First first;struct Third third;

};static const SIGSELECT exclude_sig[] = {1,FIRST};



sig = receive_all_but ((SIGSELECT *) exclude_sig);switch(sig->sig_no){

case THIRD:/* Code */

break;

default:/* Code */

}free_buf(&sig);

}}

AR

M K

erne

l


2

3

receive_fsem

Syntax union SIGNAL *receive (OSTICKS timeout, SIGSELECT *sigsel OSFSEMVAL semvalue);

Description waits for either a signal, a fast semaphore, or a time-out.

If the signal was already available, or the fast semaphore had already been signalled, thecall will return immediately. The time-out is optional: it can either be set to 0 causinga check for signal or fast semaphore. It can also be set to -1, resulting in an infinitetime-out.

Parameters timeout The time which will elapse before returning if none of the wanted sig-nals turn up and the fast semaphore is not signalled. The time may bealmost one system time shorter and many system ticks longer if otherprocesses of higher priority requests the CPU. 0 is legal and forces re-turn without any delay, i.e. checking if either a desired signal is avail-able, or if the fast semaphore had already been signalled. -1 indicatesan infinite time-out, preventing return because of time-out.

sigsel Pointer to an array of the signal numbers to receive.

semvalue Requested number of time to wait on the fast semaphore. This is usu-ally 1.


General

Receive_fsem combines wait_fsem with receive_w_tmo. It receives signals and times out in exactly the same manner as receive_w_tmo. Additionally it waits for fast semaphores much like wait_fsem. The return value indicates which type of event caused the call to return.The fast semaphore associated with the calling process is decreased by semvalue on entry to receive_fsem. The call will return immediately if the fast semaphore is still positive, i.e. if the fast semaphore had been signalled at least semvalue time before the call to receive_fsem. The call can return because of fast semaphore signalling as soon as the fast semaphore is positive.If the call returns because of another event than the fast semaphore, the fast semaphore is increased by semvalue before the call returns. This insures that no fast semaphore event is missed even if there are several simultaneous events.Receive_fsem will receive signals in exactly the same manner as receive. All signals will remain in the signal queue if a return is caused by fast semaphore signalling or a time-out.The time to wait is given in the type OSTICKS. Timeouts of 0 ticks return immediately. Timeouts set to 1 expire at the next system tick, that is after 0-1 system tick. Time-outs of 0 ticks return immediately after checking. Time-outs set to 1 expire at the next system tick, that is after 0-1 system tick. It is also possible to avoid time-outs altogether by using a time to wait value of -1.

AR

M K

erne

l


Several events may appear to occur simultaneously, e.g. if a wanted signal is sent to the process and the fast semaphore is signalled during execution of higher or equal priority processes. It cannot be known which of several simultaneous events will cause receive_fsem to return. The following is however guaranteed:

When return is caused by a signal, the first wanted signal in the signal queue will be returned.

The return value will not indicate a time-out if a signal arrives or the fast semaphore is signalled within he specified time.

If the fast semaphore had been signalled enough time before the entry to the call, the return value will be OS_RCV_FSEM.

Receive_fsem cannot be called from an interrupt process since an interrupt process can never wait for any event except interrupts.Example#include "ose.h"


union SIGNAL{SIGSELECT sig_no;};


union SIGNAL *sig;

for(;;){

/* Wait for any signal in 10 ticks time */sig = receive_fsem ((OSTICKS) 10, any_sig, 1);If (my_signal_p == NIL) {

/* Timeout has occurred */}else if (my_signal_p == (-1)){

/* Semaphore count became zero */}else {

/* A signal was received */}

}}

AR

M K

erne

l


2

3

receive_w_tmo

Syntax union SIGNAL *receive (OSTICKS timeout, SIGSELECT *sigsel);

Description Searches the signal queue of the calling process for one or more desired signals. If a de-sired signal is found, it is removed from the queue and handed over to the calling proc-ess. If none of the desired signals arrive within the specified time, receive_w_tmoreturns a NIL-pointer.

Parameters timeout The time which will elapse beforereceive_w_tmo returns, if none ofthe wanted signals turns up. The time may be almost one system timeshorter and many system ticks longer if other processes of higher pri-ority requests the CPU. 0 is legal and forces return without any delay.

sigsel Pointer to an array of the signal numbers to receive.


General

Receive_w_tmo will receive signals in exactly the same manner as receive. However, if after the specified time none of the required signals have appeared, the call to receive_w_tmo returns with a NIL-pointer.The time to wait is given in the type OSTICKS. Timeouts of 0 ticks return immediately. Timeouts set to 1 expire at the next system tick, that is after 0-1 system tick.Receive_w_tmo can not be called from an interrupt process since an interrupt process can never wait for a signal.It is guaranteed that if a signal arrives within the specified time the calling process will get that signal. If, however, a signal arrives slightly after the time has elapsed the process may get it anyway. This is due to the fact that if a process of higher priority runs, the process calling receive_w_tmo may not get the opportunity to scan the queue until after the timeout has occurred.

AR

M K

erne

l




union SIGNAL{SIGSELECT sig_no;};



/* Wait for any signal in 10 ticks time */sig = receive_w_tmo((OSTICKS) 10, any_sig);/* Check if a signal was received. If no signal was * received in 10 ms time the receive_w_tmo() sys * call will return NIL. */if (sig != NIL){

/* Code */free_buf(&sig);

}else{

/* Code */}

}}

AR

M K

erne

l


2

3

restore

Syntax void restore (union SIGNAL *sig);

Description Enters the calling process as owner and addressee of the buffer.

Parameter sig The pointer to the buffer to restore.

Caution: This call has an unusual parameter systax (pointer to thebuffer and not pointer to the pointer to the buffer).

Return Value None.

GeneralWhen a signal is sent to an external process, send will use a special buffer format when forwarding the buffer to the link handler. The link handler cannot return such buffers directly to the system; they must be re formatted. restore re formats such buffers.Any attempt to free an unrestored buffer may cause a system crash.When the DEBUG-option is used, every buffer possessed by a user process is owned by that process. When the buffer is sent/received owner is changed. Any attempt by a process to send/free a buffer it does not own is an error.If a buffer is taken over by another process without using send/receive, that process must call restore in order to be acknowledged as the new owner of the buffer. It can then be freed/sent in the ordinary manner.

AR

M K

erne

l




union SIGNAL{

SIGSELECT sig_no;};

OS_PROCESS(my_linkhandler){


/* Code */sig = receive((SIGSELECT *) any_sig);if(addressee(&sig) != current_process()){

restore(sig);/* Code */

}free_buf(&sig);

}}

AR

M K

erne

l


2

3

send

Syntax void send (union SIGNAL **sig, PROCESS to);

Description Moves a buffer from the sending process to the signal queue of the receiving process.


to The ID of the process the signal will be sent to.

In order to send a signal to a process you must have the address to theprocess. To obtain the address, simply add an underscore to the nameof the process, then declare it as an external process. The processnames are those that you specified in the osarm.con file when youconfigured your system.

Return Value None.

General

Send transfers control of a signal buffer from the sending process to the receiving process, the addressee. Each process has one, and only one, queue for signals sent to the process. Buffers are entered at the end of the signal queue of the receiving process. The sending process can no longer access the buffer.If the receiving process is of higher priority than the sending process, the sending process will be swapped out and the receiving process will be swapped in. Before sending a buffer, it must be allocated using alloc. It is also possible to send a buffer which has been received from receive.Sending Signals To Another CPUThis is done in exactly the same manner as when you send a signal to an internal process. However, you must provide the address yourself. Addresses to internal processes range from 1 to the number of processes you have. Before you can send signals to an external processor you will need to obtain or write a link handler for the physical link you intend to use.External process must have numbers in the range 0x0100 to 0xFF00, e.g. the low byte must be zero.

AR

M K

erne

l



#define FORTH 4 /* These declarations */struct forth /* are preferably made */{ /* in a .sig-file which */

SIGSELECT sig_no;/* is included. */char data;

};

extern PROCESS proc_;

union SIGNAL{

SIGSELECT sig_no;struct Forth forth;

};


union SIGNAL *sig;

for(;;){

sig = alloc(sizeof(struct forth), FORTH);sig->forth.data =x;send(&sig,proc_);/* Code */

}}

AR

M K

erne

l


2

3

sender

Syntax PROCESS sender (union SIGNAL **sig);

Description Obtains the process ID of the process which sent a buffer.


Return value Returns the process ID of the sender or zero if the signal was never sent.

GeneralSender is used to find out who sent a signal. You must have the pointer to a buffer before you may call sender, i.e. if you have sent the buffer to another process or freed it, it is too late to find out who sent it.Example#include "ose.h"


union SIGNAL{

SIGSELECT sig_no;};


union SIGNAL *sig;

for(;;){

sig = receive((SIGSELECT *) any_sig);/* Code */send(&sig, sender(&sig));

}}

AR

M K

erne

l


send_w_s

Syntax void send_w_s (union SIGNAL **sig,PROCESS from,PROCESS to);

Description Sends signals exactly like SEND, but the sender of the buffer may be set to any processID.

Parameters sig A pointer to a pointer to a signal buffer

from The ID of the process specified as sender.

to The ID of the process the signal will be sent to.

Return Value None.

GeneralThe regular send system call always enters the calling process as sender in the buffer. if this is not desired, send_w_s performs a regular send but enters the specified process as the sender in the buffer.

This might be useful to a link handler. Suppose that a signal comes to the link handler on the physical link. Once received by the link handler, the link handler may want to send the signal to the destination process. When doing that the link handler may enter the sending global process on the other side of the physical link as the sender of the signal. If the link handler was to use the regular send, the link handler would become sender, making it impossible for the receiving process to find out which process originally sent the signal.If a system has several link handlers, the process declared as LINKHANDLER will still have to forward signals from send to other link handlers. In this case send_w_s might be used, thus preserving the original senders.Note: External processes are numbered from 0x0100 to 0xFF00, i.e. the low byte must be zero.

AR

M K

erne

l


2

3


#define FIFTH 5 /* These declarations */struct fifth /* are preferably made */{ /* in a .sig-file which */


extern PROCESS proc1_;extern PROCESS proc2_;

union SIGNAL{

SIGSELECT sig_no;};



sig = alloc(sizeof(struct fifth), FIFTH);/* send a signal to proc2 specifying proc1 as sender */send_w_s(&sig, proc1_, proc2_);/* Code */

}}

AR

M K

erne

l


set_fsem

Syntax void set_fsem (OSFSEMVAL val, PROCESS pid);

Description Assigns a value to a fast semaphore.

Parameters val The initial value of the fast semaphore.

pid Process ID of the process which owns the fast semaphore whose valueis set.

Return Value None.

GeneralThis system call is used to initialise the value of a fast semaphore before normal operation begins.A fast semaphore can not be referenced until it has been initialized.It is therefore wise to have processes initialize only their own fast semaphores.Example#include "ose.h"



for(;;){

set_fsem((OSSEMVAL) 1, proc_);/* Code */

}}

AR

M K

erne

l


2

3

set_pri

Syntax void set_pri (OSPRIORITY newpri);

Description Sets a new priority level for the calling process.

Parameters newpri The desired new priority for the calling process.

Return Value None.

GeneralSet_pri is used to modify the priority level of the calling process. The call only works for prioritized processes.The call will cause a context switch if the new priority is lower or equal to the priority of another process. (Calling set_pri with the same priority as the current priority will force a context switch to the next ready process, if there are other ready processes at the same priority.)Example#include "ose.h"


OSPRIORITY org_prio;OSPRIORITY prio;

for(;;){

org_prio = get_pri(current_process());prio = set_pri(31);if(prio == org_prio && org_prio == 31){

/* Code, priority could not be set */}else{

/* Code *//* Reset the original priority */prio = set_pri(org_prio);

}}

}

AR

M K

erne

l


signal_fsem

Syntax void signal_fsem (PROCESS pid);

Description Signals a fast semaphore for the specified process.

Parameters pid The ID of the process which owns the desired semaphore.

Return Value None.

GeneralThe fast semaphore for the specified process is incremented. If it becomes zero, the process waiting at the semaphore is made ready.Example#include "ose.h"



for(;;){

/* Code */signal_fsem(proc_);/* Code */

}}

AR

M K

erne

l


2

3

signal_sem

Syntax void signal_sem (SEMAPHORE *sem);

Description increments the value of the specified semaphore and releases the first process waitingat the semaphore.

Parameters sem A pointer to the semaphore to be signaled.

Return Value None.

General

It is illegal to cause a semaphore to wrap from high positive numbers to a negative value.Example#include "ose.h"

extern SEMAPHORE *sem;


for(;;){

/* Code */signal_sem(sem);/* Code */

}}

AR

M K

erne

l


sigsize

Syntax OSBUFSIZE sigsize (union SIGNAL **sig);

Description Examines a signal buffer and reports the size that was requested when the buffer wasallocated.


Return Value Returns the number of bytes requested when the buffer was allocated

GeneralSigsize is used to find the size that was requested from alloc when a buffer was first allocated.You must have the pointer to a buffer before you may call sigsize, i.e. if you have sent the buffer to another process or freed it, it is too late to find out the size.Example#include "ose.h"


union SIGNAL{

SIGSELECT sig_no;};


union SIGNAL *sig;union SIGNAL *sig2;OSBUFSIZE size;

for(;;){

sig = receive((SIGSELECT *) any_sig);size = sigsize(&sig);sig2 = alloc(size,sig->sig_no);

/* Code */}

}

AR

M K

erne

l


2

3

start

Syntax void start (PROCESS pid);

Description Causes a stopped process to resume execution as soon as no process of higher priorityis running.

Parameters pid The ID of the process which is to be started. For details on processnames, refer to the section on send.

Return Value None.

GeneralStart is used to start a process which has been stopped using stop. If the process currently running is of lower priority than the started process, the current process will be swapped out and the stopped process will be allowed to run.Only when all calls to stop a process have been matched by the same number of calls to start the process will it be allowed to start. It is an error to start a process which is not stopped.Example#include "ose.h"



for(;;){

stop(proc_);/* Code */start(proc_);

}}

AR

M K

erne

l


stop

Syntax void stop (PROCESS pid);

Description suspends execution of the required process until it is started using the start system call.

Parameters pid The ID of the process which is to be stopped. For details on processnames, refer to the section on send.

Return Value None.

GeneralStop is used to stop a process. The process will not again be allowed to run until all processes which have stopped the process have again ordered it started using start. It is an error to start a process which has not been stopped.A stopped process will not require CPU execution time. The stop function should be used with caution.If the currently running process is stopped, another process will be allowed to run.Stop During DelayIf a process has been stopped while waiting for a delay to expire, the delay timer will continue to count. If the process is again started before the delay has expired the delay will continue and the process will not be allowed to run until the delay is finished.If, on the other hand, the delay has expired while the process was stopped, the process will be allowed to run as soon as it is started. Provided, of course, that no process of higher priority is running.Stop During receive_w_tmoIf a process which was stopped during RECEIVE_W_TMO is started before the timeout is expired and the process has not received any required signal, execution of RECEIVE_W_TMO will continue as if the process had never been stopped.Example#include "ose.h"



for(;;){

stop(proc_);/* Code */start(proc_);

}}

AR

M K

erne

l


2

3

wait_fsem

Syntax void wait_fsem (OSFSEMVAL count);

Description waits on a fast semaphore.

Parameters count The number to decrease the fast semaphore with. Requested numberof times to wait on the fast semaphore.

Return Value None.

GeneralWait_fsem waits at the fast semaphore associated to the calling process.The semaphore is decreased by the requested amount.If the result becomes negative, the calling process is suspended until the semaphore again becomes positive or zero. This occurs when some other process has signalled the semaphore a sufficient number of times.Example#include "ose.h"


for(;;){

/* Code */wait_fsem((OSFSEMVAL) 1);/* Code */

}}

AR

M K

erne

l


wait_sem

Syntax void wait_sem (SEMAPHORE *sem);

Description Waits at the specified semaphore structure.

The semaphore value is decremented. If the result is negative, the caller is suspendedand queued at the end of the semaphore queue.

Each time some other process signals the semaphore, the value is incremented and thefirst process queued at the semaphore is released

Parameters sem A pointer to the semaphore.

Return Value None.

General

The wait_sem call is not available to interrupt processes.

AR

M K

erne

l


2

3

wake_up

Syntax int wake_up (void);

Description An interrupt process can be invoked in two ways; either by a hardware interrupt or bya software event. In both cases the interrupt process is invoked with interrupts disabledup to and including the hardware priority assigned to the interrupt process.

The wake_up system call informs the interrupt process of the way in which it was in-voked. This is useful because receive calls are fairly expensive and can often not be af-forded at each hardware interrupt.

Software events that cause interrupt processes to be invoked are signal transmissions toan interrupt process.

This system call can be disabled by a configuration entry in osarm.con.

Parameters None.

Return value Returns 0 (zero) if the interrupt process was invoked by a hardware interrupt.

Returns 1 (one) if the interrupt process was invoked by a signal sent to it. The signal isready to be fetched with a receive call.

Returns 2 if the interrupt process was invoked in response to a signal_fsem call issuedby some other process. (The value of the fast semaphore is not important and can not beread with the get_fsem system call.)

If called by a process of a type other than an interrupt process, the wake_up functionreturns 1 (one).

AR

M K

erne

l



union SIGNAL{

SIGSELECT sig_no;};

OS_PROCESS(my_interrupt_process){

static const SIGSELECT all[] = {0};union SIGNAL *sig;

switch(wake_up()){

case 0:/* hardware interrupt invoked the interrupt * process */break;

case 1:/* A signal sent to this process caused the wake_up */sig = receive((SIGSELECT *)all);free_buf(&sig);break;

case 2:/*signal_fsem() on this process caused the wake_up */break;

default:/* this is an error */

}

AR

M K

erne

l

Reference Manual / 4.6 Timing Specification 61

2

3

4 Timing SpecificationThe execution times stated assume a ARM7TDMI processor running with a clock frequency of 20 MHz (OSE Epsilon for ARM in internal ROM, no wait states and external nonmultiplexed databus), and that the system has been configured for fast execution with no debug options selected. In some cases, when execution time has not been considered critical and execution time varies from time to time, the execution time is given as "roughly".

Table 2: Timing specification for ARM Kernel

System Call Processor cyclesTime in microseconds

(ARM7TDMI, 20 MHz no waitstates)

ADDRESSEE 19 2

ALLOC 95If a previously allocated buffer is available.

10

ALLOC 108If no previously allocated buffer is available.

11

ALLOC_NIL 107 11

If a previously allocated buffer is available.

Allocating buffers for the first time is slightly more expensive than reallocating a used buffer. If this time is crucial you may wish to preallocate buffers at system start.

ALLOC_NIL 120If no previously allocated buffer is available.

12

COND_HALT 77Until swap-out

7

CURRENT_PROCESS 9 1

AR

M K

erne

l

62 Timing Specification Reference Manual / 4.6

DELAY 5Delay of zero.

1For other delays, the delay may be up to almost one system tick shorter, depending on when the next system tick occurs.

DELAY 121Delay of > zero.

11

ERROR 53Jump into errorhandler.

5

FLUSH 185Varies with the number of signals removed from, and present in the queue. Add 130 cycles per wanted sig-nal.

19

FREE_BUF 71 7

GET_FSEM 15 2

GET_TICKS 9 1

RECEIVE 138If the first signal in the queue is the required one and only one signal is required.

14

RECEIVE_ALL_BUT 158If the first signal in the queue is the required one and only one signal is required.

16

RECEIVE_FSEM 138If the first signal in the queue is the required one and only one signal is required.

14




AR

M K

erne

l

Reference Manual / 4.6 Timing Specification 63

2

3

RECEIVE_W_TMO 171If the first signal in the queue is the required one and only one signal is required.Timeout = 0

17

RESTORE 46To restore any buffer.

5

RESTORE 32To restore the smallest avail-able buffer.

3

SEND 100 10

SEND_W_S 100 10

SENDER 12 1

SET_FSEM 14 1

SET_PRI 52 5

SIGNAL_FSEM 64If the semaphore value was non negative (no task switch takes place).

6

SIGSIZE 12 1

START 70 7

STOP 87 9

WAIT_FSEM 58If the semaphore becomes negative, the dispatch time has to be added.

6

DISPATCH 177Process switch

18




AR

M K

erne

l

64 Timing Specification Reference Manual / 4.6

AR

M K

erne

l

Reference Manual / 4.6 User Interface 65

2

3

5 User InterfaceThe user interface to OSE is defined in a number of C header and assembler include files, which should be included in an OSE application. These files are not affected by OSE kernel and interface library reconfiguration, even if the headers are sometimes produced by a configuration program.Header behaviour may be affected by manifest constants defined at compile time. In particular, the OS_DEBUG constant affects debugger support.Headers conform to ANSI recommendations, i.e. they use ANSI prototypes and may be included any number of times in any order.Internal OSE symbols begin with the string "zz" or "ZZ". Such symbols along with the names of all system calls, types, tags of enumerated types, macros and manifest constants are reserved by OSE. Many types begin with the letters "OS" or "ose_", so it is wise to avoid such symbols when writing an application.For more information, see Header and Include Files on page 66 and Data Types on page 67.

AR

M K

erne

l

66 Header and Include Files Reference Manual / 4.6

5.1 Header and Include FilesThe following standard headers and includes define the OSE interface:

ose.hContains variable and code address declarations to be included in prioritized and background processes written in C.

ose_i.hContains variable and code address declarations to be included in timerinterrupt and interrupt processes written in C and declared as OS_INT in the OSE Configuration entry.

ose_usr.hContains variable and code address declarations to be included in prioritized and background processes written in C and running in USR mode.

osarm.ancContains variable and code address declarations to be included in prioritized and background processes written in assembly.

osarmi.ancContains variable and code address declarations to be included in timer interrupt and interrupt processes written in assembly. It is written in assembly.

AR

M K

erne

l

Reference Manual / 4.6 Data Types 67

2

3

5.2 Data TypesThe header files described in the header files section contain several type definitions. These types are introduced to allow reasonable portability between various OSE implementations.The following types are the most important:

union SIGNAL

SIGSELECT

PROCESS

All types except unions, structures and the SEMAPHORE type, which is a typedef for the semaphore structure, are simple types. This means that in an application variables of these types can be compared safely against each other for numerical equality.The types OSSEMVAL and OSFSEMVAL are signed. Other types are unsigned. When writing an application it is necessary to declare the "union SIGNAL" type and this must be done after including the ose.h header file. All signals that are used in a file must be part of the union signal declaration in that particular file.This is done in the following way:#include "ose.h"#include "signals.sig"union SIGNAL{

SIGSELECT sig_no;struct First first;struct Testsignal testsignal;

};The sig_no variable must always be part of the union. Signal structures may also be included if they are used, preferably declared in a header file which is included. The signal structure must contain the signal number but it may also contain other variables. A declaration of a signal structure can look as follows:#define FIRST 1struct First{

SIGSELECT sig_no;

/* Here, other data can be declared if desirable forinstance: char data; */

};

AR

M K

erne

l

68 Data Types Reference Manual / 4.6

Available data types available are:

union SIGNALA signal structure

SIGSELECTA signal number

PROCESSA process ID

OSBUFSIZEThe number of bytes in a signal

OSFSEMVALA fast semaphore value

OSSEMVALA semaphore value

OSERRCODEInformation passed to error()

OSTICKSUsed by delay() and similar

AR

M K

erne

l

Reference Manual / 4.6 Error Messages 69

2

3

6 Error MessagesError messages are described in:

Run-Time Error Messages on page 70

Configuration Error Messages on page 76

For an explanation of the error information and how to write an error handler, see the ARM Kernel Users Guide.

AR

M K

erne

l

70 Run-Time Error Messages Reference Manual / 4.6

6.1 Run-Time Error MessagesThe data can be found at the ERR_MSG location. ERR_MSG[0] contains error number.Remember that these error reports are run-time errors. Unlike compiler errors, they only indicate that an error has occurred, they cannot with certainty guarantee that the reason for the error is the one listed below. A system crash or an arbitrary jump may cause any of these errors to be reported.Always keep a breakpoint set at the label Q_ERR when testing your system. When this breakpoint is reached, examine location ERR_MSG for the error number below if OSE detected the error.

Table 3: Run-time Error Messages for ARM Kernel

Error code (hex) Error

01 Attempt to allocate larger buffer than the largest size specified at system configuration. 8 buffersizes were specified in the osarm.con file before you generated the system you are running. The designated process has tried to allocate a buffer which is larger than the largest of the buffersizes.

02 The memory pool was empty when the designated process tried to allocate memory. You must allocate more memory to the memory pool or your processes must use less memory. There is also the possibility that one or more processes fail to return memory to the system.

03 The designated process called FREE providing a NIL-pointer. The process has called RECEIVE during interrupt and failed to observe that a NIL-pointer was returned. It may also have called RECEIVE_W_TMO and then failed to note that a NIL-pointer was returned.

04 The designated process tried to free a buffer which did not have the number of the process. There are two known explanations for this:

The process which allocated or received the buffer turned it over to another process using a public variable to transfer the buffer. If such is the case, you should read Buffer Transfer in Building a System. It details how to transfer buff-ers without using SEND.

The designated process has two or more pointers to the same buffer. It then used one pointer to send/free the buffer, whereupon it used another pointer to free the same buffer. Use only one pointer to each buffer.

AR

M K

erne

l

Reference Manual / 4.6 Run-Time Error Messages 71

2

3

05 The designated process called SEND_W_S providing a NIL-pointer. The process may have called RECEIVE or ALLOC during interrupt and failed to observe that a NIL-pointer was returned. It may also have called RECEIVE_W_TMO and then failed to note that a NIL-pointer was returned. This error may also indicate that a buffer was sent twice or freed before it was sent.

06 The designated process called SEND providing a NIL-pointer. The process may have called RECEIVE during interrupt and failed to observe that a NIL-pointer was returned. It may also have called RECEIVE_W_TMO and then failed to note that a NIL-pointer was returned.

07 The designated process tried to send a buffer which the process did not have. This error only occurs when the BUFFER_CHECK option has been turned off. Since buffer check is not active, there is very little information available. This could actually be any of the errors 9, 21, 22, 25, 26 or 28. Refer to these for further information.

08 Attempt to send a signal to a non-existent process.

09 The designated process tried to send a buffer which did not have the number of the process.

There are two known explanations for this:

The process which allocated or received the buffer turned it over to another process using a public variable to transfer the buffer. If such is the case, you should read Buffer Transfer in Building a system. It details how to transfer buff-ers without using SEND.

The designated process has two or more pointers to the same buffer. It has used one pointer to send/free the buffer, whereupon it used another pointer to send the same buffer. Use only one pointer to each buffer.

0A The designated process called SENDER providing an illegal pointer. The process has probably already sent the buffer or it may have freed the buffer.

0D Attempt to start process 0. Processes are numbered from 1.

0E Attempt to start an unknown process.

0F Attempt to stop process 0. Processes are numbered from 1.

10 Attempt to stop an unknown process.



AR

M K

erne

l


11 The designated process tried to free a buffer which the process did not have. This error only occurs when the BUFFER_CHECK option has been turned off. Since buffer check is not active, there is very little information available. This could actually be any of the errors 4, 21, 22, 25, 26 or 28. Refer to these for further information.

12 Attempt to send signal with illegal sender.

13 The designated process is using system call SEND_W_S and tried to send a buffer which did not have the number of the process. There are two known explanations for this:

The process which allocated or received the buffer turned it over to another process using a public variable to transfer the buffer. If such is the case, you should read Buffer Transfer in Building a System on transferring buffers. It de-tails how to transfer buffers without using SEND.

The designated process has two or more pointers to the same buffer. It has used one pointer to send/free the buffer, whereupon it used another pointer to send the same buffer. Use only one pointer to each buffer.

14 The designated process is using system call SEND_W_S and tried to send a buffer which the process did not have. This error only occurs when the BUFFER_CHECK option has been turned off. Since buffer check is not active, there is very little information available. This could actually be any of the errors 9, 21, 22, 25, 26 or 28. Refer to these for further information.

1D Stack underflow.

1E Interrupt stack overflow. Too many variables has been allocated or the pro-cedure calls have too deep nesting. The designated process is probably the one which has blown the stack.

1F Stack overflow. Too many variables has been allocated or the procedure calls have too deep nesting. The designated process is probably the one which has blown the stack.



AR

M K

erne

l


2

3

21 SEND/SEND_W_S/RECEIVE/FREE_BUF/RESTORE found a buffer whose administration block and/or identity codes were ruined. The pointer to the buffer pointed inside the pool.When searching backwards from this buffer OSE Epsilon for ARM was unable to find any correct buffer. Either this buffer was first in the pool or else the buffer pool was corrupted from the indicated address and back-wards, i. e. in the direction of decreasing addresses.

22 SEND/SEND_W_S/RECEIVE/FREE_BUF/RESTORE found a pointer which did not point inside the buffer pool. The pointer may have been uninitialised or perhaps ALLOC was never called?

23 A process has terminated. It is always illegal for a prioritized or back-ground process to terminate. You may have forgotten to jump to the begin-ning of the process or you may have POPed too much data from the stack.

24 Illegal attempt to start a process. The designated process tried to start a process which was already started. Each stop of a process must be matched by an equal number of starts. It is illegal to start a process which is not stopped.

25 SEND/SEND_W_S/RECEIVE/FREE_BUF/RESTORE found a buffer whose administration block and/or identity codes were ruined. However, the real problem could not be found.

26 SEND/SEND_W_S/RECEIVE/FREE_BUF/RESTORE found a buffer whose administration block and/or identity codes were ruined. The pointer to the buffer pointed inside the pool.When searching backwards from this buffer OSE Epsilon for ARM found a buffer whose administration block and ID-codes were correct. It is sus-pected that the process which owns this buffer is responsible for the mem-ory disruption. The process has probably written beyond the end of the buffer the process has allocated.Use signal number and other information of the buffer to locate the code of the process which has caused the error.

27 The designated process called GET_PRI providing a non-existent process.



AR

M K

erne

l


28 RECEIVE has encountered a pointer which points outside the allocated part of the buffer pool. This is often an indication of major memory corrup-tion. This error may also result if some process overwrites buffers in the queue which RECEIVE tries to traverse. Use the POOL analyse function of the debugger to check for this type of error.

29 Memory corruption. Queueheads for returned buffers have been damaged. ALLOC has found a pointer in a queuehead that does not point inside the pool.

2C An attempt was made to start an interrupt process.

2D An attempt was made to stop an interrupt process.

2E An attempt was made to restore the NIL pointer.

2F An attempt was made to restore a pointer which points outside the allocated part of the buffer pool.

30 RESTORE failed in determining buffer size, probably due to a damaged buffer.

31 SET_PRI with illegal priority argument.

32 POWER_FAIL was called but no power on routine has been declared.

33 SIGSIZE was called with the NIL pointer as a parameter. The process has probably already sent the buffer or it may have freed the buffer.

34 SET_PRI was called from an interrupt/timer-interrupt process or from a background process.

35 DELAY was called from an interrupt process. Interrupt processes and timer-interrupt processes may not call DELAY.

37 Stack overflow in interrupt process stack. Probably due to overusage by some interrupt process.

38 Stack overflow in temporary stack.

39 Stack underflow in temporary stack.

3A An attempt was made to create more than one link handler.



AR

M K

erne

l


2

3

3B During system start a process descriptor that contained an unknown process type was encountered. This is either an indication of heavy ROM corrup-tion or a CPU crash.

41 An attempt was made to free an unrestored buffer. A buffer must be restored before it is freed if its addressee does not equal current process. This occurs when OSE has redirected a buffer with an unknown destination process to a link handler.

44 Illegal buffersize found, when an attempt was made to kill signal.

45 Call to GET_FSEM with an illegal PID.

46 Call to SET_FSEM with an illegal PID.

47 Call to SET_FSEM with an illegal semaphore value.

48 Call to WAIT_FSEM with an illegal semaphore value.

49 Call to SIGNAL_FSEM with an illegal PID.

55 ADDRESSEE was called with the NIL pointer as a parameter. The process has probably already sent the buffer or it may have freed the buffer.

56 POWER_FAIL was called but no power off routine has been declared.

57 Stack overflow in second interrupt stack.

58 Stack underflow in second interrupt stack.



AR

M K

erne

l

76 Configuration Error Messages Reference Manual / 4.6

6.2 Configuration Error MessagesThese errors are reported when the program confarm runs. The input file is osarm.con and the output file is osarm.s.All such errors must be corrected before you can successfully assemble and link your system. They appear because erroneous or incompatible parameters have been entered into the configuration file osarm.con.

Table 4: Configuration Error Messages for ARM Kernel

Error code Error

1 ILLEGAL PARAMETER. An erroneous parameter has been given to an configuration entry. Check the parameters of the named configuration entry. The manual section on configuration describes exactly which parameters are legal.

2 DECLARATION DISORDER. Configuration entries was given a wrong order. If you fail to locate the trouble, copy the original configuration file and re-enter your selections.

8 ILLEGAL INTERVAL. A timer-interrupt process was declared with an illegal interval between calls to the timer-interrupt process, or a back-ground process was declared with an illegal timeslice. Legal values are in the range 1..255.

10 INTERRUPT DECLARED TWICE. The designated interrupt source was used more than once or the interrupt source does not exist. Each interrupt can have at most one interrupt process. Check the section on system con-figuration to see which interrupt sources are available. Also check that you have selected the intended CPU-type.

11 POOL TOO SMALL. The pool must be at least 48 bytes.

12 BUFFERSIZE ALIGNEMENT. Buffer sizes must be multiples of 4.

21 BUFFERSIZE DISORDER. Buffer sizes must be selected in ascending order, that is the smallest buffersize first, then the next larger, then the next larger and finally the largest.

22 BUFFERSIZE OUT OF RANGE. The largest buffer size possible is pool-size minus 24 bytes. The smallest size is 2 bytes.

27 TOO MANY PROCESSES. The total number of processes may never exceed 127.

28 ILLEGAL PRIORITY. The priority must be between 0 and 31.

39 SEND HANDLER REQUIRES DEBUG. A send handler cannot be selected unless DEBUG is set to either YES in osarm.con.

AR

M K

erne

l

Reference Manual / 4.6 Configuration Error Messages 77

2

3

40 TO MANY START HANDLERS. The maximum number of start handlers is 128.

41 ILLEGAL TIME SLICE. Zero is not allowed as time slice or init value.

Table 4: Configuration Error Messages for ARM Kernel

Error code Error

AR

M K

erne

l

78 Configuration Error Messages Reference Manual / 4.6

AR

M K

erne

l

Reference Manual / 4.6 Reserved Words 79

2

3

7 Reserved WordsA number of words are used as identifiers by OSE. These words must never be used as identifiers in your programs. Any conflicts will be accurately reported by the compiler/assembler or the linker.A further restriction is that processes may not be named in conflict with any symbol used locally within OSE. If you keep getting assembler errors on duplicate symbols you must rename the process in conflict.Avoid using symbols beginning with "zz" or "ZZ" since these are extensively used by the operating system and debugger. The most interesting of these symbols are listed below.Words reserved as identifiers by OSE.

ADDRESSEE, ALLOC ALLOC_NILCOND_HALT CREATE_SEMCURRENT_PROCESS DELAY ERROR, ERR_MSG FLUSH FREE_BUF GET_FSEMGET_SEM GET_PRIGET_TICKS KILL_SEM NILOSARMOSBUFSIZE OSDEBUG OSEOSE_IOSERRCODE OSFSEMVAL OSSEMVALOSTIME OS_PROCESS, OS_PROCESS32 OS_INT_PROCESS OS_INT_PROCESS32 POWER_FAILPROCESS Q_ERR RECEIVERECEIVE_FSM RECEIVE_W_TMO RECEIVE_ALL_BUT RESTORE SEMAPHORE SENDSEND_W_S SENDER, SET_FSEMSET_PRI SIGNAL_FSEM SIGNAL_SEMSIGSELECT SIGSIZE STARTSTOP SYSTEM_TICK TIMER_ENTRYWAIT_FSEM WAIT_SEM WAKE_UP

addressee alloc create_semcurrent_process delay errorflush free_buf get_fsemget_sem get_ticks kill_sempower_fail receive receive_w_tmorestore send send_w_ssender set_fsem signal_fsemsignal_sem sigsize startstop wait_fsem wait_semwait_sem wake_up

AR

M K

erne

l

80 Reserved Words Reference Manual / 4.6

Reference Manual

enea ose epsilon for arm release notes

Documents

ose system

retrieval system

basic system calls

advanced system calls

system calls user interface

runtime error messages

configuration error

error message guide