Kern el

OSE 

Kernel 


Reference Manual 

Enea OSE Systems AB

Copyright 

Copyright (C) 1998 by Enea OSE Systems AB. 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 OSE Systems AB. 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. 

Disclaimer 

Enea OSE Systems AB 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 OSE Systems AB reserves the right to revise this publication and to make 

changes from time to time in the contents hereof without obligation to Enea OSE Systems AB to 

notify any person of such revision or changes. 

Trademarks 

OSE is a registered trademark of Enea OSE Systems AB. 


Document No: 420e/OSE93-1 R1.0.4 

OSE / Kernel

Table Of Contents 


1 Introduction 

1.1 Purpose of this manual 1 : 1 

1.2 Who Should Read this Manual 1 : 1 

1.3 About this Manual 1 : 1 

2 System Call Summary 

2.1 System Calls in Alphabetical Order 2 : 1 

2.2 System Calls in Functional Groups 2 : 5 

2.3 System Calls in Implementation Level Groups 2 : 10 

3 System Calls 

addressee 3 : 1 

alloc 3 : 3 

assign_linkhandler 3 : 5 

attach 3 : 7 

attach_block 3 : 9 

attach_segment 3 : 10 

clear_bp 3 : 11 

create_block 3 : 13 

create_error_handler 3 : 15 

create_pool 3 : 17 

create_process 3 : 19 

create_sem 3 : 23 

current_process 3 : 25 

delay 3 : 26 

detach 3 : 27 

error 3 : 28 

error2 3 : 29 

flush 3 : 30 

free_buf 3 : 31 

get_bid 3 : 32 

get_bid_list 3 : 33 

get_cpu 3 : 35 

get_env 3 : 36 

get_env_list 3 : 37 

get_envp 3 : 39 

get_fsem 3 : 40 

get_mem 3 : 41 

get_pcb 3 : 43 

get_pid_list 3 : 47 

get_pool_list 3 : 49 

get_poolcb 3 : 50 

get_pri 3 : 53 

get_ptype 3 : 54 

get_segid 3 : 56 

get_sem 3 : 57 

get_sig_info 3 : 58 

get_sig_poolid 3 : 61 

get_signal 3 : 62 

Reference Manual / R1.0.4 OSE / Kernel - toc : 1


get_stk_poolid 3 : 64 

get_systime 3 : 65 

get_ticks 3 : 66 

get_uid 3 : 67 

hunt 3 : 68 

hunt_from 3 : 71 

intercept 3 : 73 

kill_proc 3 : 75 

kill_sem 3 : 77 

mem_move 3 : 78 

power_fail 3 : 79 

receive 3 : 81 

receive_from 3 : 83 

receive_w_tmo 3 : 85 

restore 3 : 87 

resume 3 : 89 

select_segment 3 : 91 

send 3 : 92 

sender 3 : 94 

send_w_s 3 : 95 

set_bp 3 : 96 

set_env 3 : 99 

set_envp 3 : 100 

set_fsem 3 : 101 

set_mem 3 : 102 

set_pcb 3 : 103 

set_pri 3 : 104 

set_pri_for 3 : 105 

set_redirection 3 : 106 

set_segment 3 : 108 

set_segment_mode 3 : 109 

set_sigsize 3 : 110 

set_suid 3 : 111 

sigsize 3 : 112 

signal_fsem 3 : 113 

signal_sem 3 : 114 

start 3 : 115 

start_OSE 3 : 117 

stop 3 : 118 

system_tick 3 : 119 

tick 3 : 120 

wait_fsem 3 : 121 

wait_sem 3 : 122 

wake_up 3 : 123 

NIL 3 : 125 

OS68 3 : 126 

OS_ATTACH_SIG 3 : 127 

OS_DEBUG 3 : 128 

OSE 3 : 129 

OSE_LEVEL_x 3 : 130 

OSE_I 3 : 131 

OS_PROCESS 3 : 132 



OSSIM 3 : 133 

SYSTEM_TICK 3 : 135 

4 User Interface 

4.1 Header Files 4 : 1 

4.2 Data Types 4 : 3 

5 Remote System Calls 

5.1 Signal Definitions 5 : 1 

5.2 Parameter Structures 5 : 4 

rem_clear_bp 5 : 4 

rem_create_error_handler 5 : 4 

rem_flush 5 : 4 

rem_get_cpu 5 : 5 

rem_get_env 5 : 5 

rem_get_env_list 5 : 5 

rem_get_fsem 5 : 6 

rem_get_mem 5 : 6 

rem_get_pcb 5 : 6 

rem_get_pid_list 5 : 7 

rem_get_pri 5 : 7 

rem_get_signal 5 : 8 

rem_get_uid 5 : 8 

rem_hunt 5 : 9 

rem_intercept 5 : 9 

rem_resume 5 : 9 

rem_set_bp 5 : 10 

rem_set_env 5 : 10 

rem_set_fsem 5 : 10 

rem_set_mem 5 : 11 

rem_set_pcb 5 : 11 

rem_signal_fsem 5 : 11 

rem_start 5 : 12 

rem_stop 5 : 12 

5.3 Example of a Link Handler 5 : 13 

6 Error Messages 

6.1 Kernel Error Message Reference 6 : 1 

6.1.1 Target-specific error codes 6 : 10 

6.2 Caller Information Reference 6 : 12 

6.3 Interface Library Errors 6 : 14 

6.4 Kernel Error Summary 6 : 15 

6.4.1 Target-specific error summary 6 : 17 

7 Glossary 

Appendix A ASCII Character Set 

Appendix B Portability Considerations 

Index 


1 Introduction 

1.1 Purpose of this manual 

This volume of the OSE Real Time Kernel Reference Manual contains a system call summary, a 

detailed description of every system call, specification of data types and an error message guide. 

The purpose of this manual is to provide all the necessary information for using the OSE system 

calls. The operating system is described in full in the User’s Guide. 

1.2 Who Should Read this Manual 

This manual is primarily intended for application developers. 

It is recommended that the Real Time Kernel User’s Guide be studied before reading this Reference 

Manual. 


1.3 About this Manual 

This manual provides a guide to all available system calls. It includes a system call summary with 

the system calls presented according to three different principles: alphabetical order, functional 

groups and availability at the various implementation levels. 

It also includes a section giving a detailed explanation of every system call, with examples, and a 

section discussing possible errors together with a description of all error messages. 

Reference Manual / R1.0.4 OSE / Kernel - 1 : 1 

Introduction

2 System Call Summary 

This chapter contains the OSE system call interface, i.e. all the available system calls (except for 

remote system calls), manifest constants and macros. A brief explanation is given of every call. 


2.1 System Calls in Alphabetical Order 

addressee 

alloc 

assign_linkhandler 

attach 

attach_block 

attach_segment 

clear_bp 

create_block 

create_error_handler 

create_pool 

create_process 

create_sem 

current_process 

delay 

detach 

error 

error2 

flush 

free_buf 

get_bid 

get_bid_list 

get_cpu 

get_env 

Finds the addressee of a signal. 

Allocates a buffer of requested size. 

Assigns a process as link handler to the system. 

Stores a signal buffer owned by the caller in the control block of 

the specified process or block. 

A call from OSE to tell the MMU software that a new block has 

been created. 

A call from the MMU to tell OSE that the specified block resides 

in the indicated memory segment. 

Removes a previously set breakpoint. 

Creates a block and returns the block ID. 

Creates an error handler for the specified process or block. 

The MMU creates a new pool and attaches it to the specified block. 

Creates a process as a part of the specified block and returns the 

process ID. 

Creates and initializes a semaphore. 

Returns the process-ID of the calling process. 

Puts a process to sleep for a specified number of milliseconds. 

Removes a signal that has previously been attached to a process or 

block by the caller. 

Reports an error to the OSE kernel or to the error handler if such 

exists. 


exists, with an extra user defined parameter. 

Removes all signals sent by any of a set of processes specified from 

the signal queue of a process. 

Returns a signal buffer to the pool associated with the block. 

Returns the block ID that the specified process is a part of. 

Lists all the blocks that are available to the specified user number. 

Returns an identification string of the operating system where the 

specified process is executing. 

Reads the contents of the named environment variable. 


System Call Summary


get_env_list 

get_envp 

get_fsem 

get_mem 

get_pcb 

get_pid_list 

get_pool_list 

get_poolcb 

get_pri 

get_ptype 

get_segid 

get_sem 

get_sig_info 

get_sig_poolid 

get_signal 

get_stk_poolid 

get_systime 

get_ticks 

get_uid 

hunt 

hunt_from 

intercept 

kill_proc 

kill_sem 

mem_move 

NIL 

OS_ATTACH_SIG 

Lists the environment variables available in the specified block or 

process. 

Reads a 32 bit pointer from a named environment variable for the 

specified process or block. 

Reads the current value of a fast semaphore. 

Reads data from the address space of the specified process or 

block. 

Returns the status of a specified process or block. 

Lists all the processes that are part of a specified block. 

Lists all pools that are available to the specified user number. 

Interrogates the status of the specified pool. 

Returns the priority of a process. 

Returns the type of the specified process. 

Finds the segment that the specified block or process is part of. 

Reads the current value of a semaphore. 

Extract detailed information about a signal buffer. 

Returns the ID of the signal pool associated with a specified block 

or process. 

Returns a copy of the signal located in the queue at the specified 

process. 

Returns the ID of the stack pool associated with a specified block 

or process. 

Returns the number of ticks since system start and the number of 

microseconds since the last tick. 

Returns the number of ticks since system start. 

Returns the user number of the specified process or block. 

Searches for a process by name and returns the process ID. 

Hunts for a process with the access rights evaluated for the process 

specified in the from parameter. 

Stops a process or trips a previously set breakpoint. 

Kills a process or a block. 

Returns a semaphore to the OS memory pool. 

A call from OSE requiring a block of memory to be copied from 

one memory segment to another by the MMU. 

A manifest constant defined by the OSE kernel. 

A manifest constant defining the signal number of the default 

signal created by the attach system call. 


System Call Summary


OS_DEBUG 

OS_PROCESS 

OSE 

OSE_I 

OSE_LEVEL_x 

OSSIM 

OS68 

power_fail 

receive 

receive_from 

receive_w_tmo 

restore 

resume 

select_segment 

send 

sender 

send_w_s 

set_bp 

set_env 

set_envp 

set_fsem 

set_mem 

set_pcb 

set_pri 

set_redirection 

set_segment 

A manifest constant that the user can define to enable reporting of 

file and line information and CPU registers to the debugger. 

A macro which should be used to define the entry point of a 

process. Use OSENTRYPOINT when forward-declaring an 

entrypoint. 

A manifest constant defined by ose.h. 

A manifest constant defined by ose_i.h. 

Manifest constants defined by the OSE kernel indicating the 

functional level of the kernel. 

A manifest constant which should be defined by the user when 

compiling a process for use in the OSE simulator. 

A manifest constant defined by the OSE kernel indicating which 

operating system is currently in use. 

Shuts down the system and enables the system for a subsequent 

restart. 

Receives selected signal(s). 

Like receive but it only accepts signals from a specified process. 

Receives selected signal(s) with a selectable time-out. 

Makes the caller owner of a signal and clears the redirection 

information. 

Re-enables an intercepted process or all intercepted processes in a 

block. 

A call from OSE requiring the MMU to select the address space in 

which the process about to be swapped in will run. 

Sends a signal to a destination process. 

Returns the ID of the process which last sent a specified signal. 

Sends a signal with a stated sender. 

Sets a breakpoint in a process or block. 

Creates or updates an environment string for the specified process 

or block. 

Stores a 32 bit pointer in a named environment variable. 

Initializes a fast semaphore with the specified value. 

Writes data to the address space of a specified process or block. 

Sets the CPU registers of the specified process. 

Sets a new priority level for the calling process. 

Replace the redirection table of a process. 

The effective segment number for the calling process is set by the 

MMU. 


System Call Summary


set_segment_mode 

set_sigsize 

set_suid 

signal_fsem 

signal_sem 

sigsize 

start 

start_OSE 

stop 

system_tick 

SYSTEM_TICK 

tick 

wait_fsem 

wait_sem 

wake_up 

A call from OSE telling the MMU what type of processes reside 

in the specified segment. 

Attempts to change the size of a signal buffer without actually 

reallocate and copy it. 

Temporarily assigns superuser privileges to the calling process. 

Increments a fast semaphore value. 

Increments the value of the specified semaphore. 

Returns requested size of a signal buffer. 

Starts a newly created or previously stopped block or process. 

Creates and initializes the OSE kernel. 

Stops a single process or all processes in a block. 

Returns the system tick length in microseconds. 

A manifest constant assigned the value 1000L for compatibility 

with older OSE kernels. 

Increments the system timer. 

Waits for a fast semaphore to become non-negative. 

Waits for the specified semaphore to become non-negative. 

Informs an interrupt process of how it was invoked. 


System Call Summary

2.2 System Calls in Functional Groups 

This section contains all the system calls grouped according to functionality. The memory manager 

interface is of interest only if you write a program loader or a memory protection hardware interface. 

Basic System Calls 

alloc 


error 

free_buf 

receive 

receive_w_tmo 

send 

sender 

Allocates a buffer of requested size. 

Puts a process to sleep for a specified number of milliseconds. 


exists. 

Returns a signal buffer to the pool associated with the block. 

Receives selected signal(s). 

Receives selected signal(s) with selectable time-out. 

Sends a signal to a destination process. 

Returns the ID of the process which last sent a specified signal. 


Advanced System Calls 

addressee 



error2 

get_cpu 

get_ptype 

get_ticks 

get_uid 

power_fail 

receive_from 

restore 

send_w_s 

set_sigsize 

sigsize 

start 

start_OSE 

stop 

Finds the addressee of a signal. 

Creates an error handler for the specified process or block. 

Returns the process-ID of the calling process. 


exists, with an extra user defined parameter. 

Returns an identification string of the operating system where the 

specified process is executing. 

Returns the type of the specified process. 

Returns the number of ticks since system start. 

Returns the user number of the specified process or block. 

Shuts down the system and enables the system for a subsequent 

restart. 

Like receive but it only accepts signals from a specified process. 

Makes the caller the owner of a signal and clears the signals 

redirection information. 

Sends a signal with a stated sender. 

Attempts to change the size of a signal buffer without actually 

reallocate and copy it. 

Returns requested size of a signal buffer. 

Starts a newly created or previously stopped block or process. 

Creates and initializes the OSE kernel. 

Stops a single process or all processes in a block. 


System Call Summary

system_tick 

tick 

wake_up 


Increments the system timer. 

Informs an interrupt process of how it was invoked. 


System Calls for Dynamic Processes 

attach 

create_block 


detach 

flush 

get_bid 

get_pri 

hunt 

kill_proc 

set_pri 


Network Related Calls 


hunt_from 

Stores a signal buffer owned by the caller in the control block of 

the specified process or block. 

Creates a block and returns the block ID. 

Creates a process as a part of the specified block and returns the 

process ID. 

Removes a signal that has previously been attached to a process or 

block by the caller. 

Removes all signals sent by any of a set of processes specified, 

from the signal queue of a process. 

Returns the block ID that the specified process is a part of. 

Returns the priority of a process. 

Searches for a process by name and returns the process ID. 

Kills a process or a block. 

Sets a new priority level for the calling process. 


Assigns a process as a link handler to the system. 

Hunts for a process with the access rights evaluated for the process 

specified in the from parameter. 


System Call Summary

Semaphore Calls 

create_sem 

get_sem 

kill_sem 

signal_sem 

wait_sem 

Fast Semaphore Calls 

get_fsem 

set_fsem 

signal_fsem 

wait_fsem 

Creates and initializes a semaphore. 


Returns a semaphore to the OS memory pool. 

Increments the value of the specified semaphore. 

Waits for the specified semaphore to become non-negative. 

Reads the current value of a fast semaphore. 

Initializes a fast semaphore with the specified value. 

Increments a fast semaphore value. 

Waits for a fast semaphore to become non-negative. 


Environment Variable Calls 

get_env 

get_env_list 

get_envp 

set_env 

set_envp 

System Interrogation Calls 

get_bid_list 

get_mem 

get_pcb 

get_pid_list 

get_pool_list 

get_poolcb 

get_sig_info 


get_signal 


Reads the contents of the named environment variable. 

Lists the environment variables available in the specified block or 

process. 

Reads a 32 bit pointer from a named environment variable for the 


Creates or updates an environment string for the specified process 

or block. 

Stores a 32 bit pointer in a named environment variable. 

Lists all the blocks that are available to the specified user number. 

Reads data from the address space of the specified process or 

block. 

Returns the status of a specified process or block. 

Lists all the processes that are part of a specified block. 

Lists all pools that are available to the specified user number. 

Interrogates the status of the specified pool. 

Extract detailed information about a signal buffer. 

Returns the ID of the signal pool associated with a specified block 

or process. 

Returns a copy of the signal located in the queue at the specified 

process. 

Returns the ID of the stack pool associated with a specified block 

or process. 


System Call Summary

get_systime 

set_mem 

set_pcb 

Breakpoint Calls 

clear_bp 

intercept 

resume 

set_bp 

Returns the number of ticks since system start and the number of 

microseconds since the last tick. 

Writes data to the address space of a specified process or block. 

Sets the CPU registers of the specified process. 

Removes a previously set breakpoint. 

Stops a process or trips a previously set breakpoint. 

Re-enables an intercepted process or all intercepted processes in a 

block. 

Sets a breakpoint in a process or block. 


System Calls for Memory Management 

attach_block 


create_pool 

get_segid 

mem_move 


set_segment 


set_suid 

A call from OSE to tell the MMU software that a new block has 

been created. 

A call from the MMU to tell OSE that the specified block resides 

in the indicated memory segment. 

The MMU creates a new pool and attaches it to the specified block. 

Finds the segment that the specified block or process is part of. 

A call from OSE requiring a block of memory to be copied from 

one memory segment to another, by the MMU. 

A call from OSE requiring the MMU to select the address space in 

which the process about to be swapped in will run. 

The effective segment number for the calling process is set by the 

MMU. 

A call from OSE telling the MMU what type of processes reside 

in the specified segment. 

Temporarily assigns superuser privileges to the calling process. 

Macros and Constants 

NIL 

OS_ATTACH_SIG 

OS_DEBUG 

OS_PROCESS 

OSE 

A manifest constant defined by the OSE kernel. 

A manifest constant defining the signal number of the default 

signal. 

A manifest constant that the user can define to enable reporting of 

file and line information and CPU registers to the debugger. 

A macro which should be used to define the entry point of a 

process. Use OSENTRYPOINT when forward-declaring an 

entrypoint. 

A manifest constant defined by ose.h. 


System Call Summary

OSE_I 

OSE_LEVEL_x 

OSSIM 

OS68 

SYSTEM_TICK 

A manifest constant defined by ose_i.h. 

Manifest constants defined by the OSE kernel indicating the 

functional level of the kernel. 

A manifest constant which should be defined by the user when 

compiling a process for use in the OSE simulator. 

A manifest constant defined by the OSE kernel indicating which 


A manifest constant assigned the value 1000L for compatibility 

with older OSE kernels. 



System Call Summary

2.3 System Calls in Implementation Level Groups 

This section groups the system calls according to implementation levels. Types, manifest constants 

and macros are not shown here. 

Level A is the portable set which means the smallest set of system calls available in an OSE kernel. 

Using these system calls ensures the highest degree of portability. 

Level A defines all constants and macros and all types required by system calls on that level. 

Level B defines the remaining types. 

Level A System Calls 

alloc 



error 

free_buf 

get_ticks 

receive 

receive_w_tmo 

restore 

send 

sender 

sigsize 


Level B System Calls 

Level B contains all level A system calls, with the following additions: 

addressee 

get_pcb 


get_ptype 

attach 

get_sem 

1 create_block get_systime 


get_uid 

2 create_process hunt 

create_sem 

hunt_from 

detach 

kill_proc 

flush 

kill_sem 

get_bid 

power_fail 

get_cpu 

receive_from 

get_env 

send_w_s 

get_env_list 

set_env 

get_fsem 

set_fsem 

signal_fsem 

system_tick 

signal_sem 

tick 

1. Remote systems call servers are not supported and only user number zero may 

be selected. 

2. Only phantom processes may be created and only user number zero may be 

selected 


System Call Summary

start 

start_OSE 

stop 

wait_fsem 

wait_sem 

wake_up 

Level C System Calls 

Level C contains all level B system calls, with the following additions: 

attach_block 

get_pri 


get_signal 

clear_bp 

intercept 

1 create_block resume 

create_pool 


1 create_process set_bp 

get_bid_list 

get_mem 

get_pid_list 

set_mem 

set_pri 

set_suid 


Level D System Calls 

Level D contains all level C system calls, with the following additions: 

2 create_block select_segment 

2 create_process set_segment 

mem_move 


set_segment 


1. Only user number zero may be selected. 

2. These systems are fully implemented at this level. 


System Call Summary

3 System Calls 

addressee 


Syntax 

Description 

PROCESS addressee (union SIGNAL **sig); 

Examines a signal buffer to find out to which process the buffer was originally 

sent by the sender. 

Include files #include "ose.h" 

or 

#include "ose_i.h" 

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

Return value 

Restrictions 

See also 

The process ID of the caller is returned in case the signal was sent without 

redirections. If sig has been redirected, addressee returns the process ID that was 

stated in the send or send_w_s call that caused the buffer redirection. 

Returns owner's ID if the signal was never sent. 

None. 

restore, sender, send, send_w_s 

Implementation Not implemented at level A. Full performance from level B. 

level 

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 the process with process ID "addr" 

* but was redirected to this process through the use of 

* a redirection table 

*/ 

} 


System Calls

} 

} 



addressee

alloc 


Syntax 

Description 

union SIGNAL *alloc (OSBUFSIZE size, 

SIGSELECT signo); 

Allocates a signal buffer of the specified size from the pool available to the caller's 

block. The specified signo (signal number) is entered in the first location in the 

new buffer. 

Another signal number may later be assigned to the buffer by simply storing a 

new number in the first location. 

The maximum buffer size available is dictated by sizeof(OSBUFSIZE). This 

means that if sizeof(OSBUFSIZE) returns 2 then the maximum available buffer 

size is: 

65536 (2 (sizeof(OSBUFSIZE) * 8) ) 

This rule may sometimes fail since the maximum buffer size may have been set 

to a smaller value when the pool was created. The minimum buffer size is one 

byte. 


or 


Parameters size The requested size of the buffer. 

signo 

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

Return value Returns a pointer to the new buffer. 

Restrictions 

See also 

The new buffer is owned by the calling process. A new owner can be entered only 

by using one of the system calls that operates on the buffer. It is basically illegal 

to pass control of a buffer to another process in any other way since buffers may 

then be lost in case of premature process termination. 

If you really need to pass buffers around in a disorderly manner, the restore 

system call can be used to force registration of a new owner of a buffer. 

It is an error to allocate a buffer larger than the largest buffer size available in the 

pool. Use the get_pcb system call to gain information about the largest possible 

buffer size for a process. 

free_buf, restore, sender, addressee, sigsize, create_pool, set_sigsize 

Implementation Full performance at all implementation levels. 

levels 

Example 


#define THIRD 3 /* These declarations */ 

struct Third /* are preferably made */ 

{ /* in a .sig-file which*/ 

SIGSELECT sig_no; /* should be included. */ 

}; 


alloc

union SIGNAL 

{ 


struct Third third; 

}; 


{ 


extern PROCESS proc_; 

/* Process ID for the static 

* process named "proc". 

*/ 

for(;;) 

{ 

sig = alloc(sizeof(struct third),THIRD); 

send(&sig,proc_); 

delay(100); 

} 

} 



alloc



Syntax OSBOOLEAN assign_linkhandler (char *linkname, 

PROCESS handler); 

Description A link handler is registered with OSE. 

This link handler receives remote system calls for all hunt calls specifying the 

indicated linkname as the first part of the hunt path, unless a process with a name 

matching the hunt path already exists. 

For a path name to match a link handler it is sufficient that the characters before 

the first "/"-character match the pathname of the link handler. 

For instance: 

The hunt path "helios/robin/peter" matches the link handler named "helios" as 

well as the Linkhandler named "helios/robin". 

The hunt path "helios/" also matches the "helios" link handler. 

The hunt path "/robin" matches the link handler named "". (This may look 

strange, but it is in fact possible to have a link handler with the name ""). 

Hunt calls already pending within the OSE kernel, matching the new link handler 

name, are honoured by the new link handler. 


Parameters linkname The path to the link handler. 

handler 

The process ID of the link handler. 

Return value Returns a non-zero value if another link handler with the specified name is 

already present in the caller's user number space. 

Restrictions There can be only one link handler for each linkname in each user number space. 

A link handler with user number zero (superuser) serves all user numbers, and 

therefore disallows any other Linkhandler with that name. 

There is no way to deregister a link handler. It must be killed when its services 

are no longer required. 

There is a deadlock problem that occurs when a link handler or remote call server 

issues a system call that results in a remote system call towards the same link 

handler. This problem is most easily avoided if link handlers are so designed that 

they never use any system calls from which remote system calls can result. If this 

is not possible, then such operations should be deferred to other processes related 

to the link handler. 

The assign_linkhandler call is not available to interrupt processes. 

See also hunt, hunt_from 



Example 



assign_linkhandler


{ 

char *linkh = "linkhandler"; 

PROCESS linkhand_; 

OSBOOLEAN check; 

PROCESS proc_id_; 

check = assign_linkhandler(linkh,linkhand_); 

if (check) 

{ 

/* If a non-zero value is returned in check, a 

* link handler with that name already exists. 

*/ 

} 

for(;;) 

{ 

check = hunt("linkhandler/proc", NULL, &proc_id_,NULL); 

if(check) 

{ 

/* Code */ 

} 

} 

} 



assign_linkhandler

attach 


Syntax 

OSATTREF attach (union SIGNAL **sig, PROCESS pid); 

Description This call is used in defensive programming to detect and resolve unexpected 

situations that occur when processes die during signal transactions. 

Attach stores a signal buffer owned by the caller in the control block of the 


If the sig parameter is set to NULL, the kernel automatically allocates a signal 

with signal number OS_ATTACH_SIG. 

This buffer is sent back to the caller by the kernel if the attached process or block 

is killed. The buffer will be sent back imediately to the caller if the process or 

block is already dead when issuing the attach. 

The buffer is freed by the kernel when the calling process issues a detach call for 

the previously attached process or block, using the reference ID obtained from 

attach. This works even if the attached process has been killed and the attached 

buffer waits in the caller's signal queue. 

The normal buffer examination calls like sender and addressee work on the 

returned buffer. Sender is set to the process ID of the killed process. 

OSE ensures that, when a process dies, attached signals are the last signals sent 

from the killed process. This means that it is safe for a supervising process to 

clear signal queues when a previously attached signal is received. 

The attach system call can also be used by memory manager software to supervise 

a memory segment. A segment ID obtained from either the attach_segment 

system call or the get_segid system call can be attached too. This enables a 

memory manager to be conveniently notified when a killed memory segment can 

be reclaimed. 



pid 

The ID of the specified block, process or segment to attach. 

Return value Returns a reference ID that may be used in a subsequent call to detach. 

Restrictions The order in which attached signals are returned when a process dies is 

unspecified. Also, a user can not assume that attached signals are returned 

immediately when a process dies. There is a delay caused by the fact that process 

housekeeping is performed by system daemons as a lower priority job. 

The attach call is not available to interrupt processes. 

See also detach, kill_proc, OS_ATTACH_SIG, attach_segment, get_segid 



Example 



attach

#define FORTH 4 /* These declarations */ 

struct Forth /* are preferably made */ 

{ /* in a .sig-file which */ 

SIGSELECT sig_no; /* is included. */ 

}; 

union SIGNAL 

{ 


struct Forth forth; 

}; 



{ 


OSATTREF attref; 



for(;;) 

{ 

/* Code */ 

sig = alloc(sizeof(struct forth), FORTH); 

attref = attach(&sig,proc_); 


if (sender(&sig) == proc_) 

{ 

/* Code, The process has been killed */ 

} 


{ 

/* Code */ 

} 

} 

} 


attach

attach_block 


Syntax 

void attach_block (PROCESS bid, OSSEGMENT segnum); 

Description This is a call from the memory manager block (MMU) to the kernel and is 

therefore normally not a user system call. 

The kernel tells the MMU software that a new block has been created and that it 

inherits the specified memory segment from its creator. 

The MMU may note that there is a new block in the segment. This allows the 

MMU software to map user created blocks to segments. The attach_block 

function may use system calls as if it was called from a prioritized superuser 

process. It is called in the context of the process that requires the operation, so 

attach_block can be simultaneously executed by several processes, and the calling 

process may be killed at any time. 

Any alloc calls issued by the attach_block function refer to the system pool, 

regardless of the pool attached to the calling process. 

The user ID of the calling process is temporarily set to zero for the duration of 

the attach_block call. This allows the function to communicate with system 

processes normally invisible to the calling process. 

Include files #include "ose_mmu.h" 

Parameters bid The block ID of the new block. 

segnum 

The segment the block will inherit. 

Return value None. 

Restrictions None. 

Implementation Not implemented at levels A and B. Full performance from 

levels level C. 


attach_block



Syntax PROCESS attach_segment (PROCESS bid, 

OSSEGMENT segnum); 



The MMU tells the kernel that the specified block resides in the indicated memory 

segment. 

The kernel will select that segment at each subsequent swap in of any process in 

the block. 

If attach_segment is not used for a block, then the kernel assumes that the block 

resides in the same memory segment as its creator. 

A unique segment number should normally be assigned in each attach_segment 

call. This causes the kernel to maintain intersegment memory protection and issue 

a select_segment call for each process switch between the segments. 

It is possible to specify the same segment number in several attach_segment calls. 

The kernel then creates a new segment descriptor and segment ID for each call, 

but it is assumed that the blocks reside in a shared address space. This mode of 

operation is useful when it is desired to disable memory protection between the 

involved blocks. 


Parameters bid The block ID of the specified block. 

segnum 

The segment the specified block resides in. 

Return value Returns a segment ID which is recognized by the attach and kill_proc system 

calls. Other system calls will treat this ID as "illegal". 

Attaching to this segment ID means that the caller is notified when the segment 

dies and the memory occupied by it can be reclaimed/reused. 

Killing the segment ID means that all processes in the segment are killed. 

Restrictions The attach_segment call is available only to superuser processes since segment 

numbers must be properly coordinated with the attach_block, mem_move, 

select_segment, and set_segment functions, it is assumed that segments are 

manipulated only by a single memory manager package. 

attach_segment must be called before the first process in the block is created, if 

called at all. 

Segment number zero is the supervisor space. This segment number must not be 

redefined by the memory manager. Other segment numbers are freely allocated 

by the memory manager. 

The attach_segment call is not available to interrupt processes. 

See also select_segment, set_segment_mode, mem_move, attach, kill_proc, get_segid 




attach_segment

clear_bp 


Syntax 

OSBOOLEAN clear_bp (PROCESS pid, OSADDRESS addr); 

Description This is a call from a debugger process to the kernel and is therefore normally not 

a user system call. It clears a breakpoint previously set by the caller at the 

specified address in the specified process or block. 

The trap signal that was specified in the set_bp call is returned to the caller (using 

a send call just as if the breakpoint had been reached). 

This call is used to clear previously set breakpoints without causing the target 

block to enter intercept status. It is also used to remove breakpoints that are no 

longer needed after another breakpoint has been reached. 

It is important to remember to clear breakpoints that are no longer in use. 

When the target process is killed, all breakpoints set are automatically cleared as 

if clear_bp had been called, but the signal buffers are freed by the kernel instead 

of being sent to the owner. 

When the debugger process (the caller of set_bp) is killed, any breakpoints set are 

cleared in the same way. 


Parameters pid The ID of the specified process or block. 

addr 

The adress where the breakpoint is to be cleared. 

Return value Returns non-zero if no breakpoint was set at the specified address, or if the 

breakpoint was already reached, or if the process died before reaching the 

breakpoint. 

Restrictions The breakpoint cleared must have been set by the calling process. It is illegal to 

clear a breakpoint set by another process. 

The clear_bp call is not available to interrupt processes. 

See also set_bp, intercept, resume, get_pcb 



Example 


#define TRAP_SIG 1 /* These declarations */ 

struct Trap_sig /* are preferably made */ 



}; 

union SIGNAL 

{ 


struct Trap_sig trap_sig; 

}; 

static const SIGSELECT trap_sel[] = {1, TRAP_SIG}; 


clear_bp

extern void function(void); 



{ 

union SIGNAL *trapsignal; 

for(;;) 

{ 

trapsignal=alloc(sizeof (struct trap_sig), TRAP_SIG); 

set_bp(proc_, (OSADDRESS) function, (OSADDRESS) 2, 

&trapsignal) 

/* Code */ 

trapsignal = receive_w_tmo(100, (SIGSELECT *) trap_sel); 

if(!trapsignal) 

{ 

/* Breakpoint not reached */ 

clear_bp(proc_, (OSADRESS) function); 

} 

/* Code */ 

} 

} 



clear_bp

create_block 


Syntax 

PROCESS create_block (char *name, 

OSUSER user, 

OSBOOLEAN use_remote_calls, 

PROCESS remote_call_server, 

OSBOOLEAN supervisor_mode); 

Description Creates a block descriptor owned by the specified user number. 

The memory segment is inherited from the caller, i.e. all processes in the new 

block will execute in the same memory space as the creator unless another 

memory segment is attached to the block by a memory manager prior to the first 

process being created. This may be desired when a new, separately linked 

software unit is being loaded into memory for execution. 

New block descriptors are given "stopped" status so an environment can be 

initialized before operation begins. This means that the first set of processes in a 

new block are "stopped" until started by issuing a start call for the block or for 

each process in the block. 

Until the last start call is issued, the block is owned by its creator, i.e. if the creator 

is killed before this, the child block is killed too. This mechanism ensures that 

partially created blocks are never left abandoned in the system. 

A block descriptor is removed from the system when either the block is explicitly 

killed, or the last process executing in the block is killed. 

The name parameter is a string containing the name by which the block will be 

known to the system and to the debugger. 

The user parameter is the user number under which the created block will execute. 

A value of NULL means the creator's user number, which is the value typically 

used. 

use_remote_calls is set to any non-zero value to indicate that a remote call server 

is specified in the remote_call_server parameter. 

remote_call_server, if present, is the ID of the process that will execute remote 

system calls issued towards processes in the block. This parameter is mainly used 

for phantom processes that should be managed by some link handler. This 

parameter is ignored if use_remote_calls is set to zero. 

supervisor_mode is set to any non-zero value if the processes in the block should 

be created in supervisor mode. Such processes must reside in kernel address space 

and can only be created by a superuser process (user 0) executing in supervisor 

mode. 


Parameters name A pointer to the name of the block. 

user 

The user number under which the block will execute. 

use_remote_calls Specifies whether a remote call server is used or not. 


create_block

Return value 

Restrictions 

See also 

remote_call_server The process ID of the remote call server if used. 

supervisor_mode The specified mode, non-zero means supervisor mode. 

Returns the block ID for the new block. 

Superuser blocks can only be created by a superuser process. 

Supervisor mode blocks can only be created by a superuser process (user number 

0) executing in supervisor mode itself. 

The create_block call is not available to interrupt processes. 

create_process, get_bid, get_bid_list, kill_proc, start 

Implementation Not implemented at level A. Remote system call servers are 


not allowed and only user number zero is supported at level 

B. Allows only user number zero at level C. Full performance 

at level D. 

Example 


OSENTRYPOINT new_process; 



{ 

PROCESS block_; 

PROCESS proc_; 

for(;;) 

{ 

/* Code */ 

block_ = create_block("block", 

(OSUSER) 0, 

(OSBOOLEAN) 0, 

(PROCESS) 0, 

(OSBOOLEAN) 0); 

proc_=create_process(OS_PRI_PROC, 

"proc_", 

new_process, 

200, 

16, 

(OSTIME) 0, 

block_, 

(struct OS_redir_entry *) NULL, 

(OSVECTOR) 0, 

(OSUSER) 0); 

start(block_); 

/* Code */ 

} 

} 


create_block



Syntax OSERRH *create_error_handler(PROCESS pid, 

OSERRH *entrypoint, 

OSADDRES stack_size); 

Description An error handler is created for the specified process or block and stack space is 

reserved for the handler in each process affected (also in those affected but not 

yet created). 

Any previously defined handler on that error level is replaced, and the old error 

handlers entrypoint is returned to the caller. 

If error handler stack space reserved by a previously defined error handler is larger 

than required, the stack space size is not altered. 

The entrypoint is a location within the address space of the specified block. 

Set entrypoint to NULL to remove a previously created error handler. 

An error handler behaves as a subroutine called from the process in context. The 

only difference is that the error handler has its own separate stack. 

Error handlers may use the same set of system calls as the process running when 

the error handler was invoked. 

The error handler is passed parameters containing error information and a flag set 

to a non-zero value if the call was made from user code and not from the kernel. 

The handler should return a flag set to a non-zero value if the error was managed. 

An error handler declaration looks like this: 

OSBOOLEAN err_handler(OSBOOLEAN user_called, 

OSERRCODE ecode, 

OSERRCODE extra); 

There are three levels of error handlers: The process error handler is called first 

if it is present. If it returns a flag saying that it could not manage the error, then 

the error is propagated to the next level. Otherwise the kernel returns to user code. 

(Errors considered fatal by the kernel are always propagated to the next level) 

The block error handler is called if there is no process error handler or if the 

process error handler returns an zero. The block error handler may then be able 

to resolve the situation in exactly the same manner as on the previous level. 

The kernel error handler is part of the kernel and is specified when the kernel is 

generated. This handler is called if no other error handler is present or if a 

reported error is fatal or if previous levels can not resolve the situation. 


Parameters pid The ID of the specified process. 

entrypoint The address of the error handler. 

stack_size Specifies the stack size to be used. 

Return value Returns the entrypoint of any previously defined error handler, or NULL if no 

previous error handler was defined. 


create_error_handler

Restrictions 

See also 

Error handlers used by several processes must be re-entrant, i.e they must use only 

stack variables. 

An error handler must return when it is finished. In particular, it must not use the 

longjmp directive defined in the C language. 

It is recommended that error handlers are created only for processes or blocks that 

are closely related to the caller. It is illegal to create an error handler for a block 

or process in another memory segment. 

Error codes provided by the OSE kernel as well as all symbols defined in 

ose_err.h are implementation dependent. 

The create_error_handler call is not available to interrupt processes. 

error, ose_err.h 



Example 



OSBOOLEAN pr_err_hand(OSBOOLEAN user_called, 



OSBOOLEAN bl_err_hand(OSBOOLEAN user_called, 






{ 

OSERRH errhand, old_pr_errhand, old_block_errhand; 

/* Creating a process error handler. (The entrypoint 

* to an error handler is returned in errhand if one 

* is previously defined otherwise NULL is returned, 

* there is no need to test the value). 

*/ 

old_pr_errhand = create_error_handler(proc_,(OSERRH *) 

pr_err_hand,200); 

/* Creating a block error handler. (The entrypoint to 

* an error handler is returned in errhand if one is 

* previously defined otherwise NULL is returned, 

* there is no need to test the value). 

*/ 

old_block_errhand = create_error_handler(block_,(OSERRH *) 

bl_err_hand,200); 

for(;;) 

{ 

/* Code */ 

} 

} 


create_error_handler

create_pool 


Syntax void create_pool (PROCESS bid, 

OSADDRESS base, 

OSADDRESS size, 

OSADDRESS sigsize_tab[], 

OSADDRESS stacksize_tab[]); 



The MMU creates a new pool and attaches it to the specified block and all its 

children. 

Pool space skould be allocated by the memory manager and is made known to the 

kernel by issuing this call. The pool is entirely managed by the kernel until all 

blocks using the pool are dead. At that point, pool space may be reclaimed by the 

MMU without further notice to the kernel. 

The first pool created is the system pool. The system pool is shared by all 

supervisor processes and those user processes that reside in kernel address space. 

Other pools are local pools to be used only by the specified block and its children. 

(It is possible to have local pools in kernel space too, which may be a useful 

feature when separately linked blocks are utilized in a system with no memory 

protection hardware.) 

In systems with simple memory protection hardware (fence registers) it may be 

useful to have local pools assigned only for stacks. In this way you will get a 

system with improved security without affecting performance. 

Bid is the (newly created) block to which the new pool should be attached. 

Base is the lowest address in the pool. 

Size is number of bytes reserved for the pool. 

Sigsize_tab[] is a sorted array of signal buffer sizes. 

The first location contains the number of entries in the array, excluding the count 

itself (max 8). If count = 0 then signals are allocated from the pool inherited from 

the creator or the pool already created for signals. 

Stacksize_tab[] is a sorted array of stack buffer sizes. The first location counts 

the number of entries (max 8). If count = 0 then stacks are allocated from the pool 

inherited from the creator or the pool already created for stacks. 


Parameters bid The ID of the specified block. 

base 

The lowest address in the pool. 

size 

The number of bytes reserved for the pool. 

sigsize_tab[] An array of all the available buffer sizes in the pool. 

stacksize_tab[] An array of all the available stack buffer sizes in the pool. 



create_pool

Restrictions Create_pool must be called before the first process in the block is created, if 

called at all. 

Create_pool is normally called after any call to attach_segment if that system call 

is required. Otherwise the pool will appear in the original memory segment, 

which is probably not what the caller intended. On the other hand, keeping signal 

pools in a common segment disables signal copying while maintaining code 

protection, which may sometimes be a useful and more efficient mode of 

operation. 

The get_pid_list and get_bid_list system call requires that: 

(max buffer size) > (max number of processes * sizeof(PROCESS)). 

It is also wise to set the largest buffer size to a large value, like 65535, which is 

the largest portable OSE buffersize. 

The create_pool call is not available to interrupt processes. 

See also alloc, free_buf 





create_pool



Syntax PROCESS create_process ( 

enum PROCESS_TYPE proc_type, 

char 

*name, 

OSENTRYPOINT 

*entrypoint, 

OSADDRESS stack_size, 

OSPRIORITY priority, 

OSTIME timeslice, 

PROCESS 

block, 

struct OS_redir_entry *redir_table, 

OSVECTOR 

vector, 

OSUSER 

user); 

Description Creates a process as part of the specified block. 

Prioritized, background and timer-interrupt processes must be subsequently 

started with the start system call, or the entire block can be started if only new 

processes are contained in it. 

proc_type is the type of the process. Legal values are: 

OS_PRI_PROC: for a prioritized process. 

OS_BG_PROC: for a background process. 

OS_INT_PROC: for an interrupt process. 

OS_TI_PROC: for a timer-interrupt process. 

OS_PHANTOM: for a phantom or dummy process. 

Name is a zero-terminated ASCII string that represents the process name. This 

string may in some implementations be copied by the kernel and stored in kernel 

memory. The name is used as a tag by other processes when searching for a 

process with the hunt call. The name may contain all printable characters. 

The slash (/) has special significance because it is recognized by the kernel as a 

path separator. It separates components in the name, which usually represents a 

network routing path. A link handler may however choose to use the pathname in 

any way desired. The create_process call does not manipulate the name string, it 

is just stored away, path and all. 

Entrypoint is where the process should begin execution. Portable programs 

should define the entrypoint with the OS_PROCESS macro. 

Stack_size is the number of bytes that should be allocated for the stack. Stacks 

are allocated according to a complex set of rules. Supervisor type interrupt and 

timer-interrupt processes share a common interrupt stack in kernel space. The size 

of this stack is automatically adjusted to maximum requirements. Prioritized and 

background processes allocate the user stack from the pool of the block they 

belong to, the supervisor stack is allocated from the system pool. 

Priority is the priority of the process. Legal values are 0-31. 0 is the highest 

priority. The priority is interpreted in different ways for the various process types. 

For interrupt processes it means hardware priority. The logical interrupt priority 


create_process


(0-31) maps to actual hardware priority in an implementation specific way. For 

timer-interrupt processes, it means in which order after the actual timer event the 

process is scheduled for execution. For prioritized processes, it means how 

important the process should be. For background and phantom processes it is not 

used. (You must however set the parameter to a legal value 0-31 for this as well) 

Timer process priority is an implementation option since this feature is some what 

difficult to implement efficiently. 

Timeslice is used only for timer-interrupt processes and background processes 

(some implementations allow a timeslice or pre-emption timeout also for 

prioritized processes - set it to zero if not used). For timer-interrupt processes the 

timeslice represents the number of milliseconds between each activation of the 

process. For background processes it represents the number of milliseconds the 

process is allowed to run before the next background process is scheduled. The 

stipulated time is rounded upwards to an integral number of system tick periods 

by the kernel. A timeslice of NULL means the default timeslice defined by the 

implementation. Any attempt to create a prioritized or background process with a 

timeslice longer than the default value causes the process to be created with the 

default timeslice. 

Block is the ID of the block that contains the new process. The block ID indicates 

among other things in which memory segment the process executes and which 

default user number the process has. Set block ID to zero for the new process to 

become part of the caller's block. 

Redir_table, if present, is a pointer to a redirection table that describes how 

signals sent to the created process should be redirected. It is set to zero if not 

present. If present, this structure contains an array of signal/process pairs. When 

a signal is sent to the created process, the redirection table is searched and if 

present in the table, the signal is redirected to the process that should receive the 

signal. 

The redirection table consists of an array of structures of type "struct 

OS_redir_entry", which is defined as: 

struct OS_redir_entry 

{ 

SIGSELECT sig; 

PROCESS pid; 

}; 

The first structure in the redirection table contains a count of the number of 

entries in the table including the first entry, and a process ID to which signals not 

specified in the redirection table should be sent. The count is always at least 1, 

and the default process ID may be set to zero to specify the created process. 

The kernel may or may not copy this table to kernel memory, so the user must 

assume that the table can not be subsequently altered. 

Vector is valid for interrupt processes only. It is the hardware vector number 

attached to the new process. A vector number of -1 causes the kernel to skip 


create_process


hardware vector generation. Such a process can only be invoked by sending a 

signal to it or signalling its fast semaphore. Use the wake_up() system call to gain 

knowledge about how the interrupt process was invoked. 

User is the user ID of the new process, or zero if the process should inherit the 

default user ID of the block in which it is contained. 


Parameters proc_type Specifies the type of the process. 

name 

A pointer to the name of the process. 

entrypoint The address of where the process will start execution 

stack_size Specifies the size of the stack. 

priority 

The priority level for the process. 

timeslice Number of milliseconds. 

block 

The name of the block the process will be part of. 

redir_table A pointer to the redirection table if present. 

vector 

The hardware vector number (only for interrupt processes). 

user 

Specifies the user ID of the process. 

Return value. Returns the process ID for the new process. 

Restrictions The redirection table must be built in run-time since process identities are 

unknown at compile time. 

Supervisor mode processes (part of a supervisor mode block) can only be created 

by a superuser process (user number 0), executing in supervisor mode itself. 

Only superuser processes may create processes with user numbers other than the 

caller's own usernumber. 

The create_process call is not available to interrupt processes. 

Some implementations can not create timer-interrupt processes with a timeslice 

value larger than 256 times the length of a tick. I.e. 256 * (system_tick() / 1000). 

See also current_process, create_block, kill_proc, OS_PROCESS, set_redirection, start 

Implementation Not implemented at level A. Only phantom processes and 


user number zero are allowed at level B. Only user number 

zero is allowed at level C. Full performance at level D. 

Example 


extern OSENTRYPOINT new_process; 


{ 


for(;;) 

{ 

/* Code */ 


create_process

} 

} 

proc_ = create_process(OS_PRI_PROC, 

"proc", 

new_process, 

200, 

16, 

(OSTIME) 0, 

(PROCESS) 0, 


(OSVECTOR) 0, 

(OSUSER) 0); 

start(proc_); 

/* Code */ 



create_process

create_sem 


Syntax 

SEMAPHORE *create_sem (OSSEMVAL initial_val); 

Description Creates a dynamic semaphore structure and initializes it to the value specified in 

initial_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 the pool when it is no longer in use by calling kill_sem. Semaphores are 

implicitly killed when all blocks in the memory segment of the creator terminates, 

i.e when the memory segment is reclaimed. 

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. 

They are removed from the system when the blocks using a semaphore have 

terminated and the memory manager software reclaims the memory segment. 

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. 


Parameters initial_val The initial value of the created semaphore. 

Return value A pointer to the created semaphore structure. 

Restrictions A semaphore can only be shared by processes within the same memory segment 

since the semaphore dies when the memory segment is reclaimed. If it is known 

that the segment is never killed, then a semaphore can be shared among all 

processes with access to the address space of the segment. It is the user's 

responsibility to ensure that the semaphore is not killed while it is still in use, and 

that a process is not killed while operating on a semaphore that is expected to live. 

Serious problems may otherwise arise. 

The create_sem call is not available to interrupt processes. 

See also wait_sem, signal_sem, get_sem, kill_sem 



Example 



{ 

SEMAPHORE *sem; 

for(;;) 

{ 

/* Code */ 


create_sem

} 

} 

sem = create_sem(1); 

/* Code */ 



create_sem


Syntax 

Description 

Include files 

PROCESS current_process (void); 

Determines which process is currently running. 


or 


Parameters None. 

Return value Returns the process ID of the calling process. 




Example 



{ 



for(;;) 

{ 

/* Code */ 

proc_ = current_process(); 

/* Code */ 

} 

} 


current_process



Syntax 

void delay (OSTIME timeout); 

Description Suspends the calling process for the number of milliseconds specified in the 

timeout parameter. 

The specified timeout period is converted to a number of actual system ticks 

according to the following rules: 

A value of zero returns immediately. 

A value equal to or smaller than one system tick period returns at the next system 

timer event, i.e. after anything between 0 and 1 system tick. 

A value higher than one system tick period is rounded upwards to the closest 

number of system ticks. The actual delay will vary between the calculated number 

of ticks and this value less one tick period. 

The result is that the actual delay may be up to one system tick period shorter 

than specified. 


Parameters timeout Specifies the number of milliseconds to suspend the process. 


Restrictions The delay call is not available to interrupt processes. 

See also receive_w_tmo 



Example 



{ 

for(;;) 

{ 

turn_on_lamp();/* fictive function */ 


turn_off_lamp();/* fictive function */ 


} 

} 


delay

detach 

Syntax 

void detach (OSATTREF *ref); 

Description Removes a signal previously attached by the caller. 

The ref parameter contains a pointer to the reference ID which was returned by 

the previous call to attach. 


Parameters ref A pointer to the reference ID of the previously attached 

signal. 


Restrictions It is illegal to detach a signal already received and freed by the caller. 

It is illegal for a process to use a ref parameter obtained by another process, i.e 

corresponding attach and detach calls must be made by the same process. 

The detach call is not available to interrupt processes. 

See also attach, OS_ATTACH_SIG 



Example 



union SIGNAL 

{ 


}; 

static const SIGSELECT attach_sig[2] = {1, OS_ATTACH_SIG}; 



{ 


OSATTREF attref; 

for(;;) 

{ 

attref = attach(NULL, proc_); 

/* Code */ 

sig = receive_w_tmo(0, (SIGSELECT *)attach_sig); 

if(sender(&sig) != proc_) 

{ 

detach(&attref);/* Process not dead */ 

} 

free_buf(&sig); 

} 

} 


detach

error 


Syntax 

void error (OSERRCODE ecode); 

Description Reports an error to the kernel or to the error handler possibly attached to the 

current process or block. 

The ecode parameter contains a user-defined numerical error code. This code is 

passed to the error handler for evaluation. 

It is suggested that error codes are grouped into ranges for classification of the 

error. For instance, an error code with the most significant bit set to zero can be 

interpreted as a warning while other error codes can be considered fatal for the 

calling process. 


or 


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

Return value The error call may or may not return, depending on how the error handler policy 

is implemented by the user. 




Example 



{ 

for(;;) 

{ 

/* Code */ 

error(6); 

/* Code */ 

} 

} 


error

error2 


Syntax 

void error2 (OSERRCODE ecode, OSERRCODE extra); 

Description Reports an error to the kernel or to the error handler possibly attached to the 

current process or block. 

The ecode parameter contains a user-defined numerical error code. This code is 

passed to the error handler for evaluation. 

It is suggested that error codes are grouped into ranges for classification of the 

error. For instance, an error code with the most significant bit set to zero can be 

interpreted as a warning while other error codes can be considered fatal for the 


The extra parameter is there so you can pass extra information to the error 

handler. It might be a pointer to some info that you would like to have available 

when 

handling the error in the error handler. 


or 


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

extra 

This parameter will be passed to the error handler, and show 

up as the extra parameter in the error handler. 

Return value The error call may or may not return, depending on how the error handler policy 

is implemented by the user. 


Implementation All OSE implementations might not have this system call. 


Example 



{ 

for(;;) 

{ 

const char *error_str = "This is no good"; 

/* Code */ 

error2(6, (OSERRCODE)error_str); 

/* Code */ 

} 

} 


error2

flush 

Syntax 

void flush (PROCESS *psel, PROCESS pid); 

Description 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 of process ID's. The first location contains the 

number of valid entries in the rest of the array. 

The flush call may be useful for instance when a process is unexpectedly killed, 

and other processes involved need to clear any pending transactions towards the 

killed process. 


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

pid 

The process ID of the receiving process. 


Restrictions 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 or timer-interrupt process. 

The flush call is not available to interrupt processes. 

Implementation This system call should be regarded as obsolete, and is only implemented for 


backwards compatibility reasons. 

Example 


extern PROCESS proc1_; 



{ 

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 */ 


flush

free_buf 


Syntax 

Description 

void free_buf (union SIGNAL **sig); 

Returns a signal buffer that is no longer needed to the pool associated with the 

caller's block. NIL is entered into the caller's signal pointer to avoid accidental 

reuse of the buffer. 


or 


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


Restrictions 

See also 

It is an error to free a buffer owned by another process. Such buffers must be freed 

by the owner, or ownership must be changed by calling restore before calling 

free_buf. 

Some old OSE implementations will not permit freeing redirected buffers (e.g. 

signals sent to other processors). Portable code should therefore call restore before 

freeing such buffers. New OSE implementations do not have this restriction. 

Note that many OSE calls return buffers that are allocated by the kernel. These 

buffers are typed as required by the various calls and must be cast to (union 

SIGNAL **) when freed. 

alloc, restore 



Example 



union SIGNAL 

{ 


} 


{ 


for(;;) 

{ 

/* Code */ 


/* Code */ 


} 

} 


free_buf

get_bid 

Syntax 

Description 

Include files 

PROCESS get_bid (PROCESS pid); 

Finds the block that the specified process is part of. 


or 


Parameters pid The process ID. 

Return value Returns the block ID. 

If pid is a block ID or the ID of a dead process, then the value specified in pid is 

returned from the get_bid call. Use get_ptype to test on these cases if you need to. 

Restrictions Superuser blocks can only be created by a superuser process.Supervisor mode 

blocks can only be created by a superuser process (user number 0) executing in 

supervisor mode itself. The create_block call is not available to interrupt 

processes. 

See also create_block, get_bid_list 



Example 






{ 

PROCESS bid; 

PROCESS process_; 

for(;;) 

{ 

/* Code */ 

bid = get_bid(proc_); 

/* Add new_process to the blocks to which*/ 

/* proc_ belongs */ 

process_ = create_process(OS_PRI_PROC, 

"process", 

new_process, 

200, 

16, 

(OSTIME) 0, 

bid, 


(OSVECTOR) 0, 

(OSUSER) 0); 

start(process_); 

/* Code */ 

} 

} 


get_bid

get_bid_list 

Syntax 

struct OS_pid_list *get_bid_list (OSUSER user); 

Description Lists all blocks that are available to the specified user number. 

Blocks that are owned by some other user are included if they contain at least one 

process available to the specified user. 

If user 0 is specified, this indicates the caller's user number. 

If user 0 is specified and the caller is a superuser, then all blocks in the system 

are listed. 


Parameters user Specifies the user number. 

Return value Returns NULL if there are no blocks available to the specified user. 

Otherwise get_bid_list allocates and returns a signal buffer with a structure 

containing the list of block ID's. 

The buffer must be freed by the caller when information has been extracted. The 

structure is: 


Restrictions 

See also 

struct OS_pid_list 

{ 

OSBUFSIZE count; 

PROCESS list[]; 

}; 

where count is the number of blocks and list is a variable size array containing 

the block identities. 

Only a superuser process may examine another user space. 

The get_bid_list call is not available to interrupt processes. 

get_bid, get_pcb, get_pid_list 



Example 



{ 

struct OS_pid_list *bidlist; 


PROCESS block1_; 

OSBOOLEAN exist; 

int i; 

for(;;) 

{ 

/* Code */ 

bidlist = get_bid_list(0); 

count = bidlist->count; 

exist = 0; 


get_bid_list

} 

} 

for(i = 0; i < count; i++) 

{ 

if(bidlist->list[i] == block1_) 

{ 

exist = 1; 

break; 

} 

} 

if(exist) 

{ 

/* Code, The block exists */ 

} 


{ 

block1_ = create_block("block1", 

(OSUSER) 0, 


(PROCESS) 0, 


/* Code */ 

} 



get_bid_list

get_cpu 


Syntax 

char *get_cpu (PROCESS pid); 

Description Returns a string describing the operating system on which the specified process 

is executing. 

In many cases, this information is also used indirectly to find out the CPU type. 

The string is contained in a buffer obtained from the caller's pool. This buffer 

must be returned to the pool with the free_buf call when the string has been 

extracted. 


Parameters pid The process ID of the specified process. 

Return value The returned null-terminated string has the following general format: 

"//" 

The "/" character is a general field separator. 

Only the first two fields have specified contents. 

Ex: "OSE/68360 R1.2.0" 

Restrictions The get_cpu call is not available to interrupt processes. 



Example 


union SIGNAL 

{ 


}; 


{ 

char *cpu1; 

char *cpu2; 


for(;;) 

{ 

/* Code */ 

cpu1 = (char*) get_cpu(current_process()); 

cpu2 = (char*) get_cpu(proc_); 

if(strcmp(cpu1, cpu2) == 0) 

{ 

/* Code, The processes run in exactly the same 

* operating systems (need not be in the same 

* cpu) 

*/ 

} 

free_buf( (union SIGNAL **) &cpu1); 

free_buf( (union SIGNAL **) &cpu2); 

} 

} 


get_cpu

get_env 


Syntax 

char *get_env (PROCESS pid, char *name); 

Description Reads the contents of the named environment variable for the specified process 

or block. 

Variables set with the set_envp() call can be read with the get_env() call, but the 

string returned is not easily interpreted 



name 

A pointer to the environment variable name. 

Return value Returns a buffer obtained from the caller’s pool containing the value of the 

specified environment variable. The value is always a null-terminated string. 

This buffer must be freed with free_buf by the caller when information has been 

extracted. 

Returns NULL if the specified environment variable was not found. 

Restrictions Strings that are too long to be passed in a signal buffer are truncated. 

The get_env call is not available to interrupt processes. 

See also get_env_list, get_envp, set_env, set_envp 



Example 

#include 


void print_term(void) 

{ 

char *env = get_env(current_process(), "TERM"); 

if(envbuf != NULL) 

{ 

printf("TERM=%s\n", env); 

free_buf( (union SIGNAL **) &envbuf); 

} 

} /* print_term */ 


get_env

get_env_list 


Syntax 

char *get_env_list (PROCESS pid, 

char *first_name); 

Description Lists the environment variables available in the specified process or block. 

If first_name is NULL then the returned list starts at the first variable found. 

If first_name is a valid name, then the returned list starts at the first variable name 

found after first_name. (In this way a long list can be managed.) 



first_name A pointer to an environment variablename. 

Return value Returns a buffer obtained from the caller’s pool containing the names of the 

environment variables available in the specified process or block. 

Names are separated by a single space and the entire string is null-terminated. 

Names that are too long for a single buffer are discarded from the return list. 

(Truncated names are never returned). 

The buffer must be freed by the caller when information has been extracted. 

Returns an empty string "" if the process or block has terminated or if no variables 

were found. 

Restrictions There is only one way to know if the environment contains more strings than the 

ones returned. A second get_env_list call must always be issued, specifying the 

last name in the previous list as first_name. 

The get_env_list call is not available to interrupt processes. 

See also set_env 

Implementation Not implemented at level A.Full performance from level B. 


Example 




{ 

char *envbuf; 

OSBOOLEAN exist; 

char *last; 

for(;;) 

{ 

/* Code */ 

envbuf = get_env_list(proc_, NULL); 

exist = 0; 

while(*envbuf && exist == 0) 

{ 

if(strstr(envbuf, "port")) 


get_env_list

} 

} 

{ 

exist = 1; 

} 


{ 

/* Find the last name in the buffer */ 

last = strrchr(envbuf,' '); 

if (last) 

envbuf = get_env_list(proc_, last); 


envbuf = ""; 

} 

} 

if(exist) 

{ 

/* Code, The variable exists */ 

} 


{ 

/* Code */ 

} 



get_env_list

get_envp 


Syntax OSADDRESS get_envp (PROCESS pid, char *name); 

Description Reads a 32 bit pointer from a named environment variable for the specified 

process or block. 

This call assumes that the value was set with the set_envp call, which means that 

it was stored in a special format. Variables set with the set_env call can be read 

with the get_envp call only if the value consists of exactly 8 characters. 


Parameters pid The ID of the specified block or process. Setting the pid 

parameter to zero is equivalent to using the pid of the current 

process. 

name 

A pointer to the environment variable name. 

Return value Returns the 32 bit pointer value of the environment variable. 

Returns zero if the specified environment variable was not found. 

Restrictions The get_envp call is not available to interrupt processes. 

See also get_env, get_env_list, set_env, set_envp 



Example 



{ 

int prod_data = 0xCAFE; 

OSADDRESS pa; 

for(;;) 

{ 

set_envp(0, "pd", (OSADDRESS)&proc_data); 

pa = get_envp(0, "pd"); 

if (pa != 0) 

printf("pa = %d\n", *(int *)pa); 

/* Code */ 

} 

} 


get_envp

get_fsem 

Syntax 

Description 

Include files 

OSFSEMVAL get_fsem (PROCESS pid); 

Interrogates the fast semaphore of the specified process. 


or 



Return value Returns the current value of the fast semaphore. 

Restrictions Get_fsem may also be called from interrupt and timer-interrupt processes, but it 

is an error to cause a remote system call while doing so, i.e. an interrupt or timerinterrupt 

process may not access a fast semaphore in another CPU. 

Examining the fast semaphore of an interrupt or timer-interrupt process, or a 

process without a fast semaphore, yields garbage. 

See also signal_fsem, wait_fsem, set_fsem 



Example 




{ 

OSFSEMVAL fsemvalue; 

for(;;) 

{ 

/* Code */ 

fsemvalue = get_fsem(current_process()); 

/*Code */ 

} 

} 


get_fsem

get_mem 


Syntax OSBOOLEAN get_mem (PROCESS pid, 

OSADDRESS from, 

void *to, 

OSADDRESS size); 

Description Reads a specified number of bytes from the address space of the specified process 

or block. 

This call is mainly used by debuggers to examine a program being debugged. 


Parameters pid The ID of the specified block or process. 

from 

The memory address to read from. 

to 

A pointer to the destination buffer. 

size 

The number of bytes to read. 

Return value Returns a non-zero value if an error occurred. Either the specified process/block 

could not be found, or the requested size could not be transferred. 

Restrictions The caller must be aware of the problems that occur when a program on another 

CPU type is examined. In particular if that CPU has another word length. 

The get_mem call is not available to interrupt processes. 

See also set_mem 



Example 


#define MEM 33 /* These declarations */ 

struct Mem /* are preferably made */ 



OSADDRESS address; 

}; 

union SIGNAL 

{ 


struct Mem mem; 

}; 


{ 

char to_array[10]; 

OSADDRESS array; 

OSBOOLEAN success; 


static const SIGSELECT mem_sig[] = {1, MEM}; 

for(;;) 

{ 


get_mem

} 

} 

/* Code */ 

sig = receive((SIGSELECT *) mem_sig); 

array = sig->mem.address; 

success = get_mem(sender(&sig), 

array, 

to_array, 

sizeof(to_array)); 

if(success) 

{ 

/* Code, The memory move was successful */ 

} 


{ 

/* Code, Not a successful memory move */ 

} 

/* Code */ 



get_mem

get_pcb 


Syntax 

Description 

struct OS_pcb *get_pcb (PROCESS pid); 

Interrogates the status of the specified process or block. This information is 

returned to the caller. 

The get_pcb call is mainly used by debuggers, but the process name, for instance, 

may also be of interest in some applications. 

Terminated processes may be examined, although no information of interest 

except process type is available. 

The process type field must always be tested to validate other information. 

Note that it is legal to pass an invalid process ID to this system call. This is 

allowed only for the get_pcb and get_ptype calls. The returned “type” field of the 

struct will then be set to OS_ILLEGAL. 


or 



Return value 

Returns a buffer obtained from the caller’s pool containing the OS_pcb structure. 

This buffer must be freed with free_buf when it is no longer needed. 

If the get_pcb call was not successful, a NULL pointer is returned. 

The OS_pcb structure has the following layout: (For blocks, only fields marked 

by '#' are valid.) 

struct OS_pcb 

{ 

# OSADDRESS type; /* Should be cast to */ 

/* enum PROCESS_TYPE */ 

OSADDRESS status; /* Should be cast to */ 

/* enum PROCESS_STATUS */ 

OSADDRESS priority; /* Should be cast to OSPRIORITY */ 

# OSUSER user; 

OSFSEMVAL fsemvalue; 

OSADDRESS sigqueue; 

# OSADDRESS attach_list; 

OSADDRESS stack_top; 

OSADDRESS stack_limit; 

# PROCESS remote_server; 

OSADDRESS sig_cnt_in_q; 

OSADDRESS sig_cnt_owned; 

# OSADDRESS max_sigsize; 

# OSADDRESS sigsel_size; 

OSADDRESS line; 

OSADDRESS file; 

# OSADDRESS name; 

OSADDRESS cpuregs; 

OSADDRESS wanted; 

# char strings[1]; 

}; 

where: 


get_pcb


Type contains the process type. Legal values are 

OS_BLOCK: A block was specified. 

OS_PRI_PROC: A prioritized process. 

OS_BG_PROC: A background process. 

OS_INT_PROC: An interrupt process. 

OS_TI_PROC: A timer-interrupt process. 

OS_PHANTOM: A phantom process. 

OS_ZOOMBIE: A killed process or block. 

OS_ILLEGAL: An invalid process ID was specified. 

Status contains process status. This is a bit field with zero, one, two or three bits 

set. If no bits are set, the process is ready or running. Otherwise the process is 

suspended for one or more reasons. The OS_STOPPED and OS_INTERCEPTED 

bits can be independently set. Other bits are mutually exclusive. 

Legal bit masks are: 

OS_RECEIVE: Waiting for one of the receive 

calls. 

OS_DELAY: 

Waiting for a delay call. 

OS_SEMAPHORE: Waiting at a semaphore. 

OS_FSEMAPHORE: Waiting at a fast semaphore. 

OS_REMOTE: Waiting for a remote system 

call. 

OS_STOPPED: The process was stopped. 

OS_INTERCEPTED: A breakpoint was reached. 

Priority is the priority of the process. Legal values are 0 - 31. 

User is the user number of the process. 

Fsemvalue is the current value of the fast semaphore attached to the process. The 

value is negative if the process is waiting at the semaphore or if the process does 

not have a fast semaphore. Use the status field to determine which is the case. 

Sigqueue is the address of the first signal in the signal queue. The signal queue 

can be examined by subsequent get_signal calls. 

Sigqueue = 0 if no signal is presently in the queue. 

Attach_list is the address of the first signal in the queue of attached signals. The 

attach queue can be examined by subsequent get_signal calls. Attach_list = 0 if 

no signal is attached to the process. 

Stack_top is the highest address on the stack. (The byte at the specified address 

is part of the stack.) 

Stack_limit is the lowest address on the stack. (The byte at the specified address 

is part of the stack.) The stack_top and stack_limit fields are equal if the kernel 

can not provide stack information. 

Remote_server is the ID of the process that manages remote system calls directed 

towards the examined process. 


get_pcb


Remote_server is the process ID of the examined process itself if no remote call 

server is present. 

Sig_cnt_in_q is the number of signals currently in the signal queue of the 

process. The address of the first signal is found in the sigqueue field. Please note 

that the sig_cnt_in_q field should only be used for statistics, not when traversing 

the signal queue itself. 

Sig_cnt_owned is the number of signals currently owned by the process. This 

includes signals allocated by the process and signals attached by the process, but 

not signals in the signal queue or signals handed to the hunt system call. 

Max_sigsize indicates number of bytes in the largest signal that the specified 

process or block is able to allocate. This is also the largest signal that can be 

successfully sent to a process in the block. (Other signals are lost.) 

Sigsel_size contains sizeof(SIGSELECT) for the specified process or block. 

Line is an integer containing the source code line from which the current system 

call was issued. Line is 0 if no line and file information is available. Line and file 

information is available if the specified process was compiled with the constant 

OS_DEBUG defined.(I.e. a -DOS_DEBUG flag was set when compiling). 

File is a string (in the strings array) showing the file name from which the current 

system call was issued. This field is invalid if line is 0. 

Line and file information is available if the specified process was compiled with 

the constant OS_DEBUG defined. 

Name is a string (in the strings array) showing the name of the process or block. 

Cpuregs is a string (in the strings array) showing all known CPU register values. 

The names of these are CPU dependent. 

A sample string might look like "PC=00001D34 SP=000089AB D1=0000A89". 

Registers are separated by a space. All values are in upper case hex format. 

Registers that can not be determined at a certain point are excluded from the list. 

There may be a pseudoregister named "RA". It contains the return address to user 

code while a system call is in progress. Information on CPU register values is 

available if the specified process was complied with the constant OS_DEBUG 

defined. 

Wanted is a copy (in the strings arrary) of the currently active sigselect array 

passed to receive by the examined process. The array was converted to a byte 

order suitable for the caller. The size of each entry must be calculated by the caller 

using the sigsel_size field described above. The wanted field is invalid if process 

status does not indicate OS_RECEIVE. 

If the sigsel array is unresolvable large it will be truncated. 

Strings is a variable size array containing the string pool. The string pool is used 

to store strings for file, process or block name and cpu registers. It also holds the 

wanted array. The values of those fields are not pointers, but indexes into the 

string pool. 


get_pcb

Restrictions 

See also 

There must be a buffer available in the pool that is large enough to hold the 

returned structure. Otherwise the get_pcb call will fail. 

Get_pcb may be called also from interrupt and timer-interrupt processes, but it is 

an error to cause a remote system call while doing so, i.e. an interrupt or timerinterrupt 

process may not examine a process in another CPU, and the kernel 

ignores any attempt to do so. Calling get_pcb from interrupt processes is allowed 

mainly to aid error handlers in obtaining the name of the current process. In the 

softkernel the return value for cpuregs will be an empty string. 

get_signal, get_mem, get_ptype, set_pcb 

Implementation Not implemented at level A. 

levels Full performance from level B. 

Implementations must support the "type", "status" and "name" fields. Other fields 

are optionally implemented, but must contain harmless dummy values. 

Example 


union SIGNAL 

{ 


}; 



{ 

struct OS_pcb *pcbbuf; 

static const char *name = "my_process"; 

for(;;) 

{ 

/* Code */ 

pcbbuf = get_pcb(current_process()); 

if(pcbbuf) 

{ 

switch((enum PROCESS_TYPE)pcbbuf->type) 

{ 

case OS_PRI_PROC: 

if(strcmp(&pcbbuf->strings[pcbbuf->name], name)) 

{ 

/* Code */ 

} 

break; 

default: 

/* Code */ 

break; 

} 

free_buf( (union SIGNAL **) &pcbbuf); 

} 


{ 

/* Code, Not a successful call */ 

} 

} 

} 


get_pcb

get_pid_list 

Syntax 

struct OS_pid_list *get_pid_list (PROCESS bid); 

Description Lists all processes that are part of the specified block and are available to the 


It is permitted to examine a block ID in another user space. Only processes 

available to the caller are listed. 


Parameters bid The ID of the specified block. 

Return value Returns NULL if the block has no processes available to the caller. 

Otherwise get_pid_list allocates and returns a signal buffer with a structure 

containing process ID's available to the caller in the block. 


structure is: 


{ 



}; 


Restrictions 

See also 

where count is number of processes and list is a variable size array containing the 

process identities. 

If the block contains processes that are not available to the caller, for instance 

processes running under other user numbers, these processes are not shown. 

If the block contains more processes than can be presented in the largest signal 

buffer, then the list is truncated at that size. 

The get_pid_list is not available to interrupt processes. 

get_pcb, get_bid_list 



Example 


#define START 10 /* These declarations */ 

struct Start /* are preferably made */ 



}; 

union SIGNAL 

{ 


struct Start start; 

}; 

extern PROCESS some_block_; 


get_pid_list


{ 

struct OS_pid_list *pidlist; 



int i; 

for(;;) 

{ 

/* Code */ 

pidlist = get_pid_list(some_block_); 

if(pidlist) 

{ 

count = pidlist->count; 


} 

} 

for(i = 0 ; i < count ; i++) 

{ 

/* Send the start signal to all 

* processes in the block 

*/ 

sig = alloc(sizeof(struct start), START); 

send(&sig, pidlist->list[i]); 

} 

free_buf( (union SIGNAL **) &pidlist); 

/* Code */ 

} 


{ 

/* Code, no processes available to the caller 

* in specified block 

*/ 

} 


get_pid_list

get_pool_list 

Syntax 

struct OS_pid_list *get_pool_list (OSUSER user); 

Description Lists all pools that are available to the specified user number. 

If user 0 is specified, this indicates the caller's user number. 

If user 0 is specified and the caller is a superuser, then all pools in the system are 

listed. 


Parameters user Specifies the user number. 

Return value Returns a signal buffer with a structure containing the list of pool IDs. 


structure is: 


{ 



}; 


Restrictions 

See also 

where count is the number of pools and list is a variable size array containing the 

pool identities. 

Only a superuser process may examine another user space. 

The get_pool_list call is not available to interrupt processes. 

get_poolcb, get_sig_info, get_sig_poolid, get_stk_poolid 



Example 


void list_pools(void) 

{ 

struct OS_pid_list *list = get_pool_list(0); 

if (list != NULL) 

{ 

OSBUFSIZE count = list->count; 

int i; 

} 

} 

printf("Pools: "); 

for(i = 0 ; i < count ; i++) 

{ 

printf("%#lx ", list->list[i]) 

} 

printf("\n"); 


get_pool_list

get_poolcb 

Syntax 

struct OS_poolcb *get_poolcb (PROCESS pool_id); 

Description Interrogates the status of the specified pool. This information is returned to the 

caller in a buffer. 

Note that it is legal to pass an invalid pool ID to this system call. 


Parameters pool_id The ID of the specified pool. 

Return value Returns a buffer obtained from the caller’s pool containing an OS_poolcb 

structure with information about a specified pool. The buffer must be returned to 

the system with free_buf when the information is no longer needed. 

If the get_poolcb call was not successful, a NULL pointer is returned. 

The OS_poolcb structure has the following layout: 


struct OS_poolcb 

{ 

OSADDRESS tot_size; 

OSADDRESS free_size; 

OSADDRESS fragment_info; 

OSADDRESS stk_conf_entries; 

OSADDRESS sig_conf_entries; 

OSADDRESS stk_conf_sizes; 

OSADDRESS sig_conf_sizes; 

OSADDRESS stk_alloc_sizes; 

OSADDRESS sig_alloc_sizes; 

OSADDRESS values[1]; 

}; 

where: 

Tot_size contains the total memory size (in bytes) of all pool fragments. 

Free_size contains the number of bytes never used in the pool. 

Fragment_info is an index into the values array where detailed information about 

all the pool fragments can be found. The layout of this information is as follows: 

The number of fragments in the pool can be found at: 

values[fragment_info + 0] 

The base address of fragment 0 can be found at: 


The size of fragment 0 can be found at: 


The number of bytes used for stacks in fragment 0 can be found at: 


The number of bytes used for signals in fragment 0 can be found at: 



get_poolcb


If there are more than one pool fragment the detailed information about pool 

fragment 1 starts at "values[fragment_info + 5]", which contains the base address 

of fragment 1. "values[fragment_info + 6]" contains the size of fragment 1 and so 

on. 

Stk_conf_entries is the number of configured stack sizes for this pool. 

Sig_conf_entries is the number of configured signal buffer sizes for this pool. 

Stk_conf_sizes is an index into the values array where to find an array (of size 

stk_conf_entries) with information about how the stack sizes has been configured 

for this pool. This field is only valid if the value of the stk_conf_entries field is 

greater than zero. The smallest configured stack size can be found at 

"values[stk_conf_sizes]" and largest configured stack size can be found at 

"values[stk_conf_sizes + stk_conf_entries - 1]". 

Sig_conf_sizes is an index into the values array where to find an array (of size 

sig_conf_entries) with information about how the signal buffer sizes has been 

configured for this pool. This field is only valid if the value of the 

sig_conf_entries field is greater than zero. The smallest configured signal buffer 

size can be found at"values[sig_conf_sizes]" and the largest configured signal 

buffer size can be found at "values[sig_conf_sizes + sig_conf_entries - 1]". 

Stk_alloc_sizes is an index into the values array where to find an array (of size 

stk_conf_entries) with information about how many stacks (of a certain 

configured size) are currently in use in the pool. This field is only valid if the 

value of the stk_conf_entries field is greater than zero. The number of currently 

used stacks of the smallest configured stack size in the pool can be found at 

"values[stk_alloc_sizes]" and "values[stk_alloc_sizes + stk_conf_entries - 1]" 

contains the number of currently used stacks of the largest configured stack size 

in the pool. 

Sig_alloc_sizes is an index into the values array where to find an array (of size 

sig_conf_entries) with information about how many signal buffers (of a certain 

configured size) are currently allocated in the pool. This field is only valid if the 

value of the sig_conf_entries field is greater than zero. The number of currently 

allocated signal buffers of the smallest configured signal buffer size in the pool 

can be found at "values[sig_alloc_sizes]" and "values[sig_alloc_sizes + 

sig_conf_entries - 1]" contains the number of currently allocated signal buffers of 

the largest configured signal buffer size in the pool. 

Values is a variable size array containing most of the requested pool information. 

Restrictions There must be a buffer available in the callers pool that is large enough to hold 

the returned structure. Otherwise the get_poolcb call will fail. 

The get_poolcb call is not available to interrupt processes. 

See also get_pool_list, get_sig_info, get_sig_poolid, get_stk_poolid 




get_poolcb

Example 


void list_pool_info(PROCESS pool_id) 

{ 

struct OS_poolcb *pool = get_poolcb(pool_id); 

OSADDRESS 

*value; 

OSADDRESS 

loop; 

if (pool == NULL) 


printf("Error: %#lx is not a valid pool identifier.\n", pool_id); 

return; 

} 

printf("Pool id.....: %#lx\n", pool_id); 

printf("Total size..: %lu\n", pool -> tot_size); 

printf("Never used..: %lu\n", pool -> free_size); 

printf("Stack sizes.: %lu\n", pool -> stk_conf_entries); 

if (pool -> stk_conf_entries) 

{ 

value = &pool -> values[pool -> stk_conf_sizes]; 

loop = pool -> stk_conf_entries; 

printf( " Conf.: "); 

while (loop--) 

printf( "%7lu", *value++); 

printf( "\n Alloc: "); 

value = &pool -> values[pool -> stk_alloc_sizes]; 

loop = pool -> stk_conf_entries; 



printf("\n"); 

} 

printf("Signal sizes: %lu\n", pool -> sig_conf_entries); 

if (pool -> sig_conf_entries) 

{ 

value = &pool -> values[pool -> sig_conf_sizes]; 

loop = pool -> sig_conf_entries; 

printf( " Conf.: "); 



printf( "\n Alloc: "); 

value = &pool -> values[pool -> sig_alloc_sizes]; 

loop = pool -> sig_conf_entries; 



printf("\n"); 

} 

loop = pool -> values[pool -> fragment_info]; 

value = &pool -> values[pool -> fragment_info + 1]; 

printf("Fragments: %lu\n", loop); 

printf(" %10s %10s %10s %10s %10s\n", 

"Fragment", "BaseAddr", "Size", "StkUsed", "SigUsed"); 

do 

{ 

printf(" %10lu %#010lx %10lu %10lu %10lu\n", 

loop, value[0], value[1], value[2], value[3]); 

value += 4; 

} while (--loop); 

free_buf((union SIGNAL **)&pool); 

} 


get_poolcb

get_pri 

Syntax 

OSPRIORITY get_pri (PROCESS pid); 

Description Examines the current priority of the specified process. 



Return value Returns the priority. 

Restrictions Works only for prioritized processes. The get_pri call is not available to interrupt 

processes. Returns 0 for background processes 

See also set_pri 



Example 



{ 

OSPRIORITY prio; 


} 

} 

for(;;) 

{ 

prio = get_pri(current_process()); 

if(prio != 31) 

{ 

set_pri(++prio); 

} 


{ 

set_pri(0); 

} 



get_pri

get_ptype 


Syntax 

Description 

enum PROCESS_TYPE get_ptype(PROCESS pid); 

Interrogates the type of the specified process or block. 

This call is intended for use in code that is shared by several processes of different 

types. For instance, it can be used in common code that needs to react in different 

ways to calls from interrupt processes and other types. 

The get_ptype call is special in that it can not be caught by a remote call server. 

This means that you can always find out the true process type with get_ptype. 

This is not true for the get_pcb call, and thus you may get different results from 

the two calls for the same process. 

Note that it is legal to pass an invalid process ID to this system call. This is 

allowed only for the get_pcb and get_ptype calls. 


or 



Return value Returns the process type. 

Legal values are: 

OS_BLOCK: 

A block was specified. 

OS_PRI_PROC: A prioritized process. 

OS_BG_PROC: A background process. 

OS_INT_PROC: An interrupt process. 

OS_TI_PROC: A timer-interrupt process. 

OS_PHANTOM: A phantom or dummy process. 

OS_ZOOMBIE: A killed process or block. 

OS_ILLEGAL: An invalid process ID was specified. 


See also get_pcb 




get_ptype

Example 



{ 

enum PROCESS_TYPE ptype; 

for(;;) 

{ 

/* Code */ 

ptype = get_ptype(current_process()); 

if(ptype == OS_BG_PROC) 

{ 

/* Code, specific to a background process */ 

} 


{ 

/* Code */ 

} 

} 

} 



get_ptype

get_segid 

Syntax 

PROCESS get_segid (PROCESS pid); 

Description Finds the segment that the specified block or process is part of. 



Return value Returns the segment ID. 

If pid is the ID of a dead block or process, then the value specified in pid is 

returned from the get_segid call. 

Restrictions The get_segid call is not available to interrupt processes. 

See also attach, attach_segment 



Example 





{ 

static const SIGSELECT att_sig[] = { 1, OS_ATTACH_SIG }; 


PROCESS sid; 

sid = get_segid(proc_); 

(void)attach(NULL, sid); 

for(;;) 

{ 

sig = receive((SIGSELECT *) att_sig); 

if (sender(&sig) == sid) 

{ 

printf("The segment containing proc_ has died!\n"); 

} 


stop(current_process()); 

} 

} 


get_segid

get_sem 

Syntax 

Description 

Include files 

OSSEMVAL get_sem (SEMAPHORE *sem); 



or 


Parameters sem A pointer to the specified semaphore. 

Return value Returns the current semaphore value. 


See also wait_sem, signal_sem, create_sem, kill_sem 



Example 



extern SEMAPHORE *sem; 


{ 

OSSEMVAL semvalue; 

for(;;) 

{ 

/* Code */ 

semvalue = get_sem(sem); 

if(semvalue == 5) 

{ 

/* Code */ 

} 


{ 

/* Code */ 

} 

} 

} 


get_sem

get_sig_info 


Syntax 

Description 

OSBOOLEAN get_sig_info (struct OS_sig_info *sig_info, 

PROCESS pool_id, 

PROCESS pid, 

OSADDRESS sig); 

Extract detailed information about a signal buffer and searches for the next buffer 

owned by a specified process in a specified pool. 

The sig_info parameter should contain a pointer to a result buffer. It is updated 

with information about the signal buffer pointed out by the sig parameter. Set 

sig_info to NULL if you don't want that information. 

The pool_id and pid parameters are used to specify how to search for the next 

buffer. The pool_id parameter specifies which pool to search. A value of zero 

allows the search to continue in any pool. The pid parameter, if non zero, specifies 

that only buffers owned by that process should be searched for. A value of zero 

allows any owner including buffers owned by the system. 

As a special case, the pool_id parameter may be set to a block id to specify the 

signal pool associated with that block. 

The sig parameter contains the address of the signal buffer to check. Set it to zero 

to request a search for the first signal in the first pool that matches the pool_id 

and pid parameters. Then use the value of the "next" field in the sig_info structure 

for subsequent calls until the next field becomes zero. This way you can traverse 

all signals in a pool. 


or 


Parameters sig_info A pointer to a result buffer. 

pool_id 

The ID of the pool in which to search. 

pid 

Search only for signals owned by the process with this ID. 

sig 

A pointer to signal to examine. 

Return value Returns a status code with either of these values: 

0. Unimplemented system call. No result is obtained. 

1. The sig parameter points to a valid signal buffer. 

2. The sig parameter points to a signal buffer which seems to be ok, apart from 

the fact that it lacks a valid endmark. 

3. The sig parameter points to a signal buffer with a broken (somehow faulty) 

signal administration block. 

4. The sig parameter is a wild pointer (not pointing at any signal buffer) inside 

a pool. 

5. The sig parameter is a wild pointer not inside any pool. 


get_sig_info

If you are unauthorised to look at the specified signal buffer (you don't have the 

right user number) the result will be the same as calling get_sig_info with a wild 

signal pointer value in the sig parameter (i.e. 4). 

If the sig_info parameter is not NULL it should contain a pointer to a OS_sig_info 

structure which will be updated with information about the signal buffer pointed 

out by the sig parameter. The structure is: 

struct OS_sig_info 

{ 


PROCESS owner; 

PROCESS sender_pid; 

PROCESS addressee_pid; 

OSBUFSIZE sig_size; 

OSBUFSIZE size_in_pool; 

OSADDRESS next; 

}; 


where: 

Sig_no is set to the signal number. 

Owner is set to process ID of the owner of the signal. If this value is zero this 

means that the signal is owned by the system. Signals who has been returned to 

the system by a call to free_buf or is located in the signal queue of a process are 

owned by the system and yields zero in this field. 

Sender_pid is set to the process ID of the sender of the signal. If the signal was 

never sent it will be set to the same value as the owner field. 

Addressee_pid is set to the process ID of the addressee of the signal, but only if 

the signal has been redirected, otherwise it will be set to the same value as the 

owner field. 

Sig_size is set to to the size value used when the signal was allocated. 

Size_in_pool is set to the number of bytes the signal occupies in the user pool. If 

memory model 1 is used an additional signal administration block is allocated in 

the system pool, the size of this signal administration block is typically 32 bytes. 

Next is set to the address of the next signal buffer owned by the specified process 

in the specified pool. If the pid parameter to get_sig_info was set to zero it will 

be set to the next signal buffer owned by anyone. 

Restrictions Fields related to the sig parameter can be trusted only if the get_sig_info call 

returns 1 or 2. The next field can be trusted only if the get_sig_info call returns 

1 or 2, or if the sig parameter was set to zero, in which case get_sig_info returns 

5. It is unwise to call get_sig_info for a process that is not stopped or intercepted, 

since signal pointers age rapidly. 

See also get_pool_list, get_poolcb, get_sig_poolid, get_stk_poolid 




get_sig_info

Example 


void list_my_sigs(void) 

{ 

struct OS_sig_info sig_info; 

PROCESS curr = current_process(); 

PROCESS sig_pool = get_sig_poolid(curr); 

OSBOOLEAN status = get_sig_info(&sig_info,sig_pool,curr,0); 

if (status == 5 && sig_info.next) 

{ 

do 

{ 

OSADDRESS sigptr = sig_info.next; 


} 

} 

status = get_sig_info(&sig_info, sig_pool, curr, sig_info.next); 

printf("sigptr........: %#lx \n", sigptr); 

switch (status) 

{ 

case 1: 

break; 

case 2: 

printf("No valid endmark found\n"); 

break; 

case 3: 

printf("The signal's administration block is faulty\n"); 

return; /* Not safe to continue */ 

case 4: 

printf("The signal's address is wild (inside a pool)\n"); 


case 5: 

printf("The signal's address is wild (not inside any pool)\n"); 


default: 

return; 

} 

printf(" sig_no.......: %#lx\n", sig_info.sig_no); 

printf(" owner........: %#lx\n", sig_info.owner); 

printf(" sender_pid...: %#lx\n", sig_info.sender_pid); 

printf(" addressee_pid: %#lx\n", sig_info.addressee_pid); 

printf(" sig_size.....: %#lx\n", sig_info.sig_size); 

printf(" size_in_pool.: %#lx\n", sig_info.size_in_pool); 

} while (sig_info.next); 


get_sig_info


Syntax 

PROCESS get_sig_poolid (PROCESS bid); 

Description Returns the ID of the signal pool associated with a specified block or process. 


Parameters bid The ID of the specified block or process. 

Return value The ID of the signal pool associated with a specified block or process. 

If bid is the ID of a dead block or process, then the value specified in bid is 

returned from the get_sig_poolid call. 


See also get_pool_list, get_poolcb, get_sig_info, get_stk_poolid 



Example 


void show_my_sig_poolid(void) 

{ 

PROCESS poolid = get_sig_poolid(current_process()); 


printf("My signal pool ID: %#lx", poolid); 

} 


get_sig_poolid

get_signal 


Syntax OSBOOLEAN get_signal (PROCESS pid, 

OSADDRESS mailptr, 

union SIGNAL **sig_copy, 

OSADDRESS *nextsig); 

Description This is a debugger call. 

Returns in sig_copy a copy of the signal located in the signal queue or attach list 

for the specified process or block. (Only processes have signal queues.) 

The signal copy is returned in a signal buffer obtained by get_signal. This buffer 

can be examined with the sender, sigsize and addressee system calls. The buffer 

must be freed with free_buf by the caller when information has been extracted. 

mailptr is a signal queue pointer obtained from get_pcb or from a previous 

get_signal call. (You can not evaluate these pointers with get_mem since signal 

buffers are not always stored in the address space of the addressee process.) 

The signal structure itself is not altered in any way, just copied byte by byte. It is 

important to understand this since sizeof(SIGSELECT) as well as other signal 

data may vary between systems. Thus the caller must realize that if the examined 

process runs on another processor, signal data must be interpreted according to 

the conventions used in that processor. 

A pointer to the next signal in the list is returned in nextsig. A zero value is placed 

in nextsig if there are no more signals in the list. Nextsig may be used as input to 

another get_sig call. 



mailptr 

A pointer to the signal queue. 

sig_copy A pointer to a pointer to the signal buffer in which the signal 

is returned. 

nextsig 

A pointer to the next signal in the queue. 

Return value Returns a non-zero value if the call failed. 

This occurs for instance if the signal queue of the specified process has been 

altered by an intermediate call to receive, flush, kill_proc or any other system call 

that alters the contents of the relevant buffer lists. When this happens, the list must 

be re-examined from the top, i.e a new list head must be obtained from get_pcb. 

Restrictions It is unwise to call get_signal (as well as get_pcb) for a process that is not stopped 

or intercepted, since signal pointers age rapidly. 

The get_signal call is not available to interrupt processes. 




Example 


get_signal




union SIGNAL 

{ 


}; 


{ 

struct OS_pcb *pcbbuf; 

OSADDRESS sigptr; 


OSADDRESS next; 

OSBOOLEAN nosuccess; 

for(;;) 

{ 

/* Code */ 

stop(proc_); 

pcbbuf = get_pcb(proc_); 

sigptr = pcbbuf->sigqueue; 

nosuccess = get_signal(proc_, sigptr, &sig,&next); 


} 

} 

while(nosuccess) 

{ 

/* If a non-zero value was returned the call was 

* unsuccessful both the get_pcb and get_signal 

* calls must be repeated 

*/ 

pcbbuf = get_pcb(proc_); 

sigptr = pcbbuf->sigqueue; 

nosuccess = get_signal(proc_, sigptr, &sig,&next); 

} 

do 

{ 

if(sender(&sig) == proc2_) 

{ 

/* Code */ 

} 


get_signal(proc_, next, &sig, &next); 

} while(next != NULL); 

free_buf((union SIGNAL **)&pcbbuf); 

start(proc_); 

/* Code */ 


get_signal


Syntax 

PROCESS get_stk_poolid (PROCESS bid); 

Description Returns the ID of the stack pool associated with a specified block or process. 


Parameters bid The ID of the specified block or process. 

Return value The ID of the stack pool associated with a specified block or process. 

If bid is the ID of a dead block or process, then the value specified in bid is 

returned from the get_stk_poolid call. 


See also get_pool_list, get_poolcb, get_sig_info, get_sig_poolid 



Example 


void show_my_stk_poolid(void) 

{ 

PROCESS poolid = get_stk_poolid(current_process()); 


printf("My stack pool ID: %#lx", poolid); 

} 


get_stk_poolid

get_systime 


Syntax 

Description 

OSTICK get_systime (OSTICK *microsecs); 

This call is mainly used by debuggers. Shows the number of system ticks since 

system start and the number of microseconds since the last tick. 

The system ticks counter is reset to zero each time the kernel is restarted. 

The system ticks counter is incremented each time the system clock is advanced 

i.e when the tick system call is issued and wraps after a fairly long period of time. 

If microsecs == NULL, then the number of microseconds is not returned. 


or 


Parameters microsecs A pointer to the returned number of microseconds. 

Return value 

Restrictions 

See also 

Returns the number of system ticks since system start. Returns the number of 

microseconds since the last tick in the microsecs parameter. No two subsequent 

calls to get_systime will ever return the same microsecond value, even if no 

hardware counter is available. 

Few systems can actually provide an accurate timing reference at the microsecond 

level. The actual resolution of the microseconds counter must therefore be 

determined for each target hardware. 

get_ticks 



Example 



{ 

OSTICK systick; 

OSTICK micro; 

for(;;) 

{ 

/* Code */ 

systick = get_systime(&micro); 

/* Code */ 

} 

} 


get_systime

get_ticks 


Syntax 

Description 

Include files 

Parameters 

Return value 

Restrictions 

See also 

OSTICK get_ticks (void); 

Shows the number of system ticks since system start. The system ticks counter is 

set to zero when time the kernel is started. 

The counter is incremented each time the system clock is advanced (i.e. when the 

tick system call is issued). 

The counter wraps after a fairly long period of time. 

The get_ticks system call may be defined as get_systime(NULL). 


or 


None. 

Returns system time in ticks. 

None. 

tick, get_systime 



Example 



{ 

OSTICK tick; 

for(;;) 

{ 

/* Code */ 

tick = get_ticks(); 

/* Code */ 

} 

} 


get_ticks

get_uid 

Syntax 

OSUSER get_uid (PROCESS pid); 

Description Finds the user number under which the specified process or block is executing. 



Return value Returns the user ID of the examined process. Returns the user ID of the caller if 

the examined process has terminated. 

Restrictions The get_uid call is not available to interrupt processes. 

See also create_block, create_process 

Implementation Not implemented at level A. Full performance at level B. 


Example 




{ 

OSUSER id; 


for(;;) 

{ 

/* Code */ 

id = get_uid(current_process()); 


id, 


(PROCESS) 0, 


/* Code */ 

} 

} 


get_uid

hunt 


Syntax OSBOOLEAN hunt (char *name, 

OSUSER 

user, 

PROCESS 

*name_, 

union SIGNAL **hunt_sig); 

Description Searches for a process by name and updates the name_ parameter with the 

process ID of the named process. 

The name_ parameter may be set to NULL if no return value variable is provided. 

This may be convenient when a hunt_sig is present. 

Only processes with the specified user number are searched for. A user parameter 

set to zero specifies the caller's user number, not the superuser. 

Processes are searched for in the following order: 

1. Processes within the caller's block. 

2. Processes that are "block processes" in other blocks. 

3. Processes in other blocks. 

4. The relevant link handler is asked for the process ID. 

If the process is found immediately, the ID of the found process is returned in the 

name_ variable. 

An optional hunt signal may be specified. This signal is stored within the kernel 

until the process appears on the network or the caller terminates. Hunt_sig may 

be set to NULL to indicate that no hunt signal is provided. 

When the process is found or created, the hunt signal is returned to the caller, and 

the process ID of the found process can be extracted with the sender call. 

The hunt signal is immediately returned if the process was immediately found, i.e 

if a hunt signal is specified, it should always be received, either immediately or 

later on. 

If the process was not found in the current CPU, and the process name contains 

a path that matches a link handler, then the hunt request is passed on to that link 

handler as a remote system call. Remote system calls are described in the Remote 

System Calls chapter. 

The link handler has several options at this point: 

1. It may return a value indicating that the process was not found. The hunt 

signal is then stored within the kernel until the link handler or someone else 

creates a process with a matching name. At that point the hunt signal is sent 

to the caller. An invalid process ID is propagated to the caller in the name_ 

variable. (If someone else created a process with the required name during the 


hunt


remote call, that process ID is returned to the caller when the kernel 

recognizes a link handler failure.) 

2. It may create a new process or use an existing process with the desired name 

and return that process ID. The kernel returns the hunt signal to the caller. 

The returned process ID is propagated to the caller in the name_ variable. 

3. It may create a new process or use an existing process with another name and 

return that process ID, indicating to the caller that the obtained process ID is 

a "private" ID. The process ID is propagated to the caller in the name_ 

variable. The hunt signal is also immediately returned to the caller, regardless 

of the fact that no matching name was ever found. This scheme allows the 

link handler to create new instances of a service process for each hunt that is 

issued, using the path name merely as a request for some service. 

The kernel frees the pending hunt signal if the calling process dies. 


Parameters name A pointer to the specified process name. 

user 

The user number. 

name_ 

The ID of the found process. 

hunt_sig A pointer to the hunt signal buffer if specified. 

Return value The name_ parameter, if present, is updated with the found process ID. The ID 

is guaranteed to be invalid if the process was not immediately found. 

The call returns zero if the process could not be found immediately. If a hunt 

signal was given by the caller, it is stored in the kernel until a matching process 

appears at a later time. 

Returns a non-zero value if the process was found immediately. Any hunt signal 

provided is returned to the caller. 

The returned value is further subdivided to indicate the scope of the found 

process. This is important only to link handlers when propagating hunt requests. 

If the hunt call returns 1, then the found process is "public", meaning that access 

to it is not restricted to any particular process. 

If the hunt call returns 2, then the found process is "private", meaning that access 

is restricted to the client process that hunted for it. This restriction is not enforced 

by the kernel, but a link handler is assumed to delete the private process when the 

client terminates. 

Restrictions The kernel may reallocate the space occupied by the hunt signal. Thus, the pointer 

to the hunt signal is not valid following the call to hunt. 

The hunt call is not available to interrupt processes. 

See also attach, detach, assign_linkhandler 



Example 



hunt

#define SIXTH 6 /* These declarations */ 

struct Sixth /* are preferably made */ 



}; 


extern PROCESS huntproc_; 

union SIGNAL 

{ 


struct Sixth sixth; 

}; 


{ 

OSBOOLEAN check; 

union SIGNAL *huntsignal; 


for(;;) 

{ 

/* Code */ 

huntsignal = alloc(sizeof(struct sixth), SIXTH); 

check = hunt("proc", 0, &huntproc_, &huntsignal); 

if(check) 

{ 

huntsignal = receive((SIGSELECT *) any_sig); 

free_buf(&huntsignal); 

} 

/* Code */ 

} 

} 


hunt

hunt_from 


Syntax OSBOOLEAN hunt_from (char *name, 

OSUSER 

user, 

PROCESS 

*name_, 

union SIGNAL **hunt_sig, 

PROCESS 

from); 

Description This is a system call intended mainly for link handlers and other network 

software. You should not require this call unless you are writing such software. 

Hunt_from does what hunt does, except that access rights are evaluated for the 

process specified in the from parameter (usually a phantom process created by the 

caller). 

This makes a true difference only if hunt causes a remote system call to some 

other link handler, and that link handler uses the hunt remote call to register new 

clients. 

In this case the other link handler should register the from parameter as a client. 

Response to the remote call must be sent to the caller 

(= sender(rem_call_sig)) as always. 

A user parameter set to zero implies the user number of the process in the from 

parameter. 

The optional hunt signal is eventually returned to the caller, not to the process 

specified in the from field. 

The kernel frees the pending hunt signal if the calling process dies or if the 

process specified in the from field dies. 


Parameters name A pointer to the specified process name. 

user 

The user number. 

name_ 

The ID of the found process. 

hunt_sig A pointer to the hunt signal buffer if specified. 

from 

The ID of the process specified as hunter. 

Return value See the hunt system call. 

Restriction See the hunt system call. 

See also hunt, attach, detach, assign_linkhandler 



Example 


#define FIRST 1 /* These declarations */ 

struct First /* are preferably made */ 




hunt_from

}; 

union SIGNAL 

{ 


struct Firsth first; 

}; 

static SIGSELECT sig_sel[] = {0}; 


OSENTRYPOINT phant; 

OS_PROCESS(my_linkhandler) 

{ 


PROCESS phantom_; 

union SIGNAL *huntsig; 

struct OS_redir_entry redir_table[1]; 

redir_table[0].sig = (SIGSELECT) 1; 

redir_table[0].pid = current_process(); 


for(;;) 

{ 

sig = receive((SIGSELECT *) sig_sel); 

switch(sig->remote_call.call_type) 

{ 

case REM_HUNT: 

sig->sig_no=REMOTE_RESPONSE; 

sig->remote_response.results.remr_hunt.found=1; 

phantom_ = create_process(OS_PHANTOM, 

"proc", 

phant, 

0, 

0, 

(OSTIME) 0, 

(PROCESS) 0, 

&redir_table, 

(OSVECTOR) 0, 

(OSUSER) 0); 

sig->remote_response.results.remr_hunt.pid = phantom_; 

send(&sig, sender(&sig)); 

huntsig = alloc(sizeof(struct first), FIRST); 

hunt_from("linkhandler2", 

0, 

&proc_, 

&huntsig, 

current_process()); 

break; 

} 

} 

} 


hunt_from

intercept 


Syntax 

Description 

void intercept (PROCESS pid); 

This system call is mainly used by debuggers. The intercept call stops a process 

as if a breakpoint was reached. 

Status for the specified process or for all processes in the specified block is 

changed to intercepted. This means that processes are permanently swapped out 

until allowed to continue with the resume call. 

If any breakpoints with a zero attribute are set in the processes, then these 

breakpoint signals are returned to their respective owners. Breakpoints set with 

non-zero attributes are not affected. 

There are no intercept counters in the system. Intercepting a process that is 

already intercepted performs no operation. 


or 




Restrictions 

See also 

Only prioritized, background and timer-interrupt processes can be intercepted. 

The intercept and resume calls have no effect on process types that can not be 

intercepted. 

Intercept may also be called from interrupt and timer-interrupt processes, but it is 


process may not intercept a process in another CPU, and the kernel 

ignores any attempt to do so. 

resume, set_bp, clear_bp, get_pcb, alloc 

Implementation Not implemented at levels A and B. Full performance from levelslevel C. 

Example 






}; 

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


union SIGNAL 

{ 


struct First first; 

}; 


intercept


{ 


for(;;) 

{ 

trapsignal = alloc(sizeof(struct first), FIRST); 

set_bp(proc_, (OSADDRESS) function, (OSADDRESS) 0, 

&trapsignal); 

intercept(proc_); 

trapsignal = receive_w_tmo(0, (SIGSELECT *) any_sig); 

if(trapsignal) 

{ 

free_buf(&trapsignal); 

} 

/* Code */ 

resume(proc_); 

} 

} 



intercept

kill_proc 


Syntax 

void kill_proc (PROCESS pid); 

Description Kill a process or a block or segment. 

If a block is specified, then all processes known to the caller in that block are 

killed. If there are no processes left, the block descriptor is then deleted too. 

(If the caller can see only some processes, then only those are killed. This is 

sufficient for the block to disappear for the caller.) 

If a single process is specified, then that process only is killed, unless it is the last 

process in a block, in which case the block is deleted too, as described above. 

In any case, all signals attached to killed processes and blocks and segments are 

eventually returned to their respective owners. 

If a killed process owns other blocks, signal buffers, semaphores, hunt signals etc, 

these are returned to the system. If a killed process was a link handler, then that 

information is deleted from the kernel lists. 

If a killed process was a remote system call server to some other blocks, then all 

those blocks are killed too. 

The kill_proc system call can also be used by memory manager software, MMS 

to kill a memory segment. A segment ID obtained from either the attach_segment 

system call or the get_segid system call can be passed to kill_proc, which causes 

deletion of all processes and blocks in the memory segment. 


Parameters pid The ID of the specified block, process or segment. 


Restrictions Killing a static process is allowed by the kernel only when the process is part of 

a separately linked software unit (program), otherwise it is an illegal operation. 

Killing a static process causes the software unit (program) to terminate in most 

implementations. This behaviour is achieved by interactions between the OSE 

interface library and user-provided memory management and program loader 

software. Other rules may apply as desired for each system. 

When the kill_proc system call is executed, the kernel removes the affected 

process(es) and blocks from system tables and invokes the lower priority system 

daemon to return attached signals and clean up at a later time. Kill_proc returns 

to the caller before this work begins. This has some important implications: 

1. A significant amount of time may elapse before attached signals are returned. 

2. Excessive process creation and destruction may exhaust system resources. 

3. When a remote call server is killed, served blocks disappear at a later time. 

The kill_proc call is not available to interrupt processes. 

See also create_block, create_process, attach_segment, attach 




kill_proc

Example 




{ 


for(;;) 

{ 

proc_ = create_process(OS_PRI_PROC, 

"process", 

new_process, 

200, 

16, 

(OSTIME) 0, 

(PROCESS) 0, 


(OSVECTOR) 0, 

(OSUSER) 0); 

/* Code */ 

kill_proc(proc_); 

} 

} 



kill_proc

kill_sem 

Syntax 

void kill_sem (SEMAPHORE *sem); 

Description Return a semaphore created by create_sem to the pool. 


Parameters sem A pointer to the semaphore. 


Restrictions Make sure no process is using the semaphore when it is killed. 

Never kill a statically declared semaphore structure by calling kill_sem. (A 

statically declared semaphore is initialised at declaration). 

The kill_sem call is not available to interrupt processes. 

See also create_sem, signal_sem, wait_sem, get_sem 



Example 




{ 


for(;;) 

{ 

/* Code */ 

sem = create_sem(1); 

/* Code */ 

kill_sem(sem); 

} 

} 


kill_sem

mem_move 


Syntax OSBOOLEAN mem_move (OSSEGMENT src_segment, 

OSADDRESS src_begin, 

OSADDRESS size, 

OSSEGMENT dest_segment, 

OSADDRESS dest_begin); 

Description This is a call from the kernel to the memory manager block. It is thus not a user 

system call. 

The kernel requires a block of memory to be copied from one memory segment 

to another. The MMU software performs this operation. 

The mem_move function may use system calls as if it was called from a 

prioritized superuser process. It is called in the context of the process that requires 

the operation, so mem_move can be simultaneously executed by several 

processes, and the calling process may be killed at any time. 

Any alloc calls issued by the mem_move function refer to the system pool, 

regardless of the pool attached to the calling process. 

The user ID of the calling process is temporarily set to zero for the duration of 

the mem_move call. This allows the mem_move function to communicate with 

system processes normally invisible to the calling process. 

The mem_move function should use set_segment calls to temporarily select 

segments while copying. When copying is complete, the home segment is 

reselected with a final set_segment call. Note that each set_segment call issued 

may indicate that the segment has been killed, in which case copying must be 

aborted. 


Parameters src_segment 

src_begin 

size 

dest_segment 

dest_begin 



Restrictions The mem_move function itself must reside in supervisor space (segment zero). 

See also set_segment, select_segment, set_segment_mode, attach_segment 

Implementation Not implemented at levels A, B and C. Full performance at 

levels level D. 


mem_move

power_fail 


Syntax 

Description 

Include files 

Parameters 

Return value 

Restrictions 

void power_fail (void); 

Shuts down the system in a manner which enables immediate continuation at a 

subsequent restart. When power reappears, the calling process (and all others) 

appears to be continuing where it left off at the time of the power_fail system call. 

The call to power_fail causes the current process to be swapped out, and a userwritten 

power fail handler is called to save memory contents and i/o status. When 

this is complete, the handler should shut down the CPU. 

If power_fail is called from an interrupt process, then the system shutdown 

procedure is deferred until execution returns to a non-interrupt level. 

When the system restarts, the kernel calls a power on handler which determines 

if memory and i/o can be restored. If this is the case, the kernel immediately 

swaps in the process that called power_fail, unless an interrupt process called 

power_fail, in which case the kernel swaps in the process that was swapped out 

when the interrupt process was called. Otherwise an ordinary cold start is 

performed. 


or 


None. 

None. 

This system call may only be used by a superuser process (user number 0). Use 

of the power_fail system call requires careful system planning since many 

hardware problems must be correctly addressed. In particular, it must be possible 

to reinitialize all i/o devices to the exact state that was present at the shutdown. 

Hints: 

• A good memory backup power system is required, including protection against 

spurious memory cycles during periods of unstable power. 

• A reliable power fail interrupt is needed. This interrupt should not be an NMI 

since non-maskable interrupts can not communicate with the kernel. 

• A watchdog timer is needed since memory backup designs may be somewhat 

unreliable. 

• It is a good idea to have hardware support for determining if a cold start is 

required. 

• Software should be planned in a way that promotes saving the i/o state. Doing 

this correctly is an art. 



Example 



power_fail


{ 

for(;;) 

{ 

/* Code */ 

power_fail(); 

/* Code, This is where the system starts again at 

* power up if a warm start 

*/ 

} 

} 



power_fail

eceive 


Syntax 

Description 

union SIGNAL *receive (SIGSELECT *sigsel); 

Receives a signal from the caller's signal queue. If an appropriate signal is not 

immediately available, the caller pends until an appropriate signal is sent to the 

caller by some other process. 

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.) 

A "negative receive specification" feature is supported. This means that if the first 

location of the sigsel array contains a negative count, then any signal except those 

that match the sigsel array is received. This feature effectively inverts the 

semantics of the receive, receive_w_tmo and receive_from calls, providing a 

means of holding back certain signals. 

The SIGSELECT type is an unsigned type, so using a negative receive 

specification requires the count in the sigsel array to be initialized with a proper 

cast expression. 


or 


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

Return value 

Restrictions 

See also 

Returns a pointer to the received signal buffer. This buffer is owned by the caller 

from that moment. 

None. 

send, send_w_s, receive_w_tmo, receive_from, alloc, free_buf, sender, sigsize, 

addressee 



Example 






}; 


receive

#define FIFTH 5 /* These declarations */ 

struct Fifth /* are preferably made */ 



}; 

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 */ 

}; 



{ 



for(;;) 

{ 


switch(sig->sig_no) 

{ 

case THIRD: 

/* Code */ 

break; 

case FIFTH: 

/* Code */ 

break; 

default: 

/* Code */ 

} 


} 

} 


receive

eceive_from 


Syntax union SIGNAL *receive_from (OSTIME timeout, 

SIGSELECT *sel, 

PROCESS from); 

Description Works like receive_w_tmo, but signals are only accepted from a specific process. 

This call is used, for instance, in interface libraries which hide signal transactions 

towards a server process from a user. In this case it must be possible to define 

signals to the server without conflicts with user signal numbers. 

The receive_from call should be used with some caution since extensive use can 

easily cause a messy system design and lead to debugging problems. 


Parameters timeout The number of milliseconds to wait. 

sel 

Pointer to an array of the signal numbers to receive. 

from 

The ID of the process to receive from. 

Return value Returns a pointer to the received signal buffer or the NIL pointer if no signal 

arrived within the specified timeout. 

Restrictions There is no way to issue receive_from without a timeout. If no timeout is required, 

a loop can be used without causing much overhead. 

For example: 

See also 

while(NIL == (sig = receive_from((OSTIME)-1, ...))); 

The receive_from call is not available to interrupt processes. 

alloc, free_buf, addressee, send, send_w_s, receive, receive_w_tmo 



Example 






}; 





}; 

union SIGNAL 

{ 


struct First first; 

struct Third third; 

}; 


receive_from


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

extern PROCESS sending_proc_; 

extern PROCESS sending_proc2_; 


{ 



for(;;) 

{ 

sig = receive_from(10, 

(SIGSELECT *) any_sig, 

sending_proc_); 

if(sig != NIL) 

{ 

if(sig->sig_no == THIRD) 

{ 


sig = receive_from(55, 

(SIGSELECT *) sig_one, 

sending_proc2_); 


{ 

/* Code */ 


} 

} 


{ 

/* Code */ 


} 


{ 

/* Code */ 

} 

} 

} 


receive_from

eceive_w_tmo 


Syntax union SIGNAL *receive_w_tmo (OSTIME timeout, 

SIGSELECT *sel); 

Description Short for receive with timeout. Works like receive, except that the caller is 

suspended no longer than the number of milliseconds specified in the timeout 

parameter. 

If the requested signal has not arrived by then, the NIL pointer is returned. 

The specified timeout period is converted to a number of actual system ticks 

according to the following rules: 

A value of zero returns immediately. 

A value equal to or smaller than one system tick period returns at the next system 

timer event, i.e. after anything between 0 and 1 system tick. 

A value higher than one system tick period is rounded upwards to the closest 

number of system ticks. The actual delay may varies between the calculated 

number of ticks and this value less 1 tick period. 

The result is that the actual delay may be up to one system tick period shorter 

than specified. 


Parameters timeout The number of milliseconds to wait. 

sel 

A pointer to an array of the signal numbers to receive. 

Return value Returns a pointer to the received signal buffer or the NIL pointer if no signal 

arrived within the specified timeout. 

Restrictions The receive_w_tmo call is not available to interrupt processes. 

See also alloc, addressee, free_buf, send, sender, send_w_s, receive, receive_from 



Example 



union SIGNAL 

{ 


}; 


{ 


for(;;) 

{ 

/* Wait for any signal in 10 ms time */ 

sig = receive_w_tmo((OSTIME) 10, any_sig); 

/* Check if a signal was received. If no signal was 


receive_w_tmo

} 

} 

* received in 10 ms time the receive_w_tmo() sys 

* call will return NIL. 

*/ 

if (sig != NIL) 

{ 

/* Code */ 


} 


{ 

/* Code */ 

} 



receive_w_tmo

estore 


Syntax 

Description 

void restore (union SIGNAL *sig); 

Registers the caller as the current owner of a signal buffer and clears buffer 

redirection information from it. Use this call if: 

1. A redirected buffer is to be reused without reallocation or 

2. A buffer has been illegally transferred from one process to another. 

The restore call should only be needed on rare occasions. 


or 


Parameters sig A pointer to the specified signal buffer. 


Restrictions 

See also 

Caution! This call has an unusual parameter syntax. In systems with multiple 

address space, it is an error to restore a buffer that is not in the callers address 

space. Some old OSE implementations do not allow a redirected buffer to be freed 

without restoring it. New implementations should avoid this problem. 

If a killed process is part of a design which passes buffers around without proper 

ownership control, then the following problem may arise: the killed process owns 

a buffer which is currently in use by some other process. Once the owner is killed, 

the buffer is returned to the pool without the knowledge of the process which uses 

the buffer. If that process chooses to send or free the buffer, the system may crash. 

Summary: If you use kill_proc extensively, never transfer buffers between 

processes without using one of the send system calls. 

alloc, free_buf, send 



Example 



union SIGNAL 

{ 


}; 


{ 


for(;;) 

{ 

/* Code */ 


if(addressee(&sig) != current_process()) 

{ 


restore

} 

} 

restore(sig); 

/* Code */ 

} 




restore

esume 


Syntax 

Description 

void resume (PROCESS pid); 

This system call is mainly used by debuggers. 

The resume call starts processes previously stopped with the intercept call or by 

a breakpoint. 

Intercept status for the specified process or for all processes in the specified block 

is removed. This means that the process(es) are allowed to continue operation as 

implied by the state present before they were intercepted. 

If any breakpoints with a zero attribute are set in the processes, then these 

breakpoint signals are returned to their respective owners. Breakpoints set with 

non-zero attributes are not affected. 

There are no intercept counters in the system. Resuming a process that is not 

intercepted performs no operation. 


or 




Restrictions 

See also 

Only prioritized, background and timer-interrupt processes can be intercepted. 

The intercept and resume calls have no effect on process types that can not be 

intercepted. 

Resume may also be called from interrupt and timer-interrupt processes, but it is 


process may not resume a process in another CPU, and the kernel 

ignores any attempt to do so. 

intercept, set_bp, clear_bp, get_pcb 


levels. level C. 

Example 



struct Fifth /* are preferably made */ 



}; 

union SIGNAL 

{ 


struct Fifth fifth; 

}; 



void function(void); 


resume


{ 


for(;;) 

{ 

trapsignal = alloc(sizeof(struct fifth), FIFTH); 

set_bp(proc_, (OSADDRESS) function,0,&trapsignal); 

trapsignal = receive((SIGSELECT *) any_sig); 

switch(trapsignal->sig_no) 

{ 

case FIFTH: 

resume(proc_); 

/* Code */ 

break; 

default: 

/* Code */ 

} 

} 

} 



resume



Syntax 

Description 

Include files 

Parameters 

Return value 

Restrictions 

void select_segment (OSSEGMENT segnum); 

This is a call from the kernel to the memory manager block and is therefore not 

a user system call. 

The select_segment function is called by the OSE dispatcher when it swaps in a 

user mode process and requires the MMU to select the address space where the 

process is located. 

The select_segment function may also be called in response to a set_segment 

system call issued from memory management software. 

#include "ose_mmu.h" 

segnum 

None. 

The select_segment function is called both in the context of a process and by the 

dispatcher in a state when no process is in context. This means that the 

select_segment function may be called concurrently by several processes, and that 

the calling process can be killed at any time unless interrupts are disabled. 

Some implementations disable interrupts during dispatcher calls to 

select_segment, so interrupt status must be preserved by the select_segment 

function. 

It is important that the code is efficient since select_segment is called for every 

process switch. No system calls may be used by select_segment. 




select_segment

send 


Syntax 

Description 

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

Sends a signal buffer to a specified addressee process and enters NIL into the 

caller's signal pointer to avoid accidental reuse of the buffer. 

The calling process is no longer the owner of the signal. 

Signals are redirected if the addressee process has a redirection table that matches 

the sent signal. 

(The signal is not redirected if the redirection table chain is infinite or indicates 

that the signal should be sent to the caller.) 

If the addressee process has terminated, the signal is quietly killed. The caller will 

never know. 


or 


Parameters sig A pointer to the signal buffer. 

to 

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


Restrictions 

See also 

A sender process can only reach the addressee if at least one of the following 

conditions is true. 

1. The sender is a superuser process, i.e it has user number 0. 

2. The sender and addressee processes have the same user number. 

3. The sender and addressee processes are part of the same block. 

These rules are re-evaluated for each hop in the redirection chain, i.e. the final 

addressee may not be known to the calling process. (The calling process is the 

"sender" for the first hop. For subsequent hops, the process with the redirection 

table is considered "sender" when the rules are re-evaluated.) 

Interrupt processes and timer-interrupt processes may exchange signals (in both 

directions) only with processes that are part of the same block. 

Interrupt processes and timer-interrupt processes may not exchange signals with 

other interrupt or timer-interrupt processes. Some OSE implementations may 

relax this restriction if the hardware architecture allows this. 

send_w_s, receive, receive_w_tmo, receive_from 



Example 


#define FORTH 4 /* These declarations */ 

struct forth /* are preferably made */ 




send

char 

}; 

data; 


union SIGNAL 

{ 


struct Forth forth; 

}; 


{ 


for(;;) 

{ 

sig = alloc(sizeof(struct forth), FORTH); 

sig->forth.data =’x’; 

send(&sig,proc_); 

/* Code */ 

} 

} 



send

sender 

Syntax 

Description 

Include files 

PROCESS sender (union SIGNAL **sig); 

Finds the process which last sent a specified signal buffer. 


or 



Return value Returns the process ID of the sender or the owner's ID if the signal was never sent. 

The sender is not affected by signal redirection, i.e the sender is always the 

process which called send or the process ID that was specified in send_w_s. 


See also addressee, restore, send, send_w_s 



Example 




union SIGNAL 

{ 


}; 


{ 


for(;;) 

{ 


/* Code */ 

send(&sig, sender(&sig)); 

} 

} 


sender

send_w_s 


Syntax void send_w_s (union SIGNAL **sig, 

PROCESS 

from, 

PROCESS 

to); 

Description Short for send with sender. Works like send, except that the signal buffer is tagged 

with the specified process ID in place of the caller's. 

If the addressee process or the specified sender process has terminated, the signal 

is quietly killed. The caller will never know. 


or 



from 

The ID of the process specified as sender. 

to 

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


Restrictions See send 

See also send, receive, receive_w_tmo, receive_from 



Example 



struct fifth /* are preferably made */ 



}; 



union SIGNAL 

{ 


}; 


{ 


for(;;) 

{ 

sig = alloc(sizeof(struct fifth), FIFTH); 

/* send a signal to proc2 specifying proc1 as sender */ 

send_w_s(&sig, proc1_, proc2_); 

/* Code */ 

} 

} 


send_w_s

set_bp 


Syntax OSBOOLEAN set_bp (PROCESS pid, 

OSADDRESS 

address, 

OSADDRESS 

attribute, 

union SIGNAL **trapsig); 

Description This is a debugger system call. 

Set_bp sets a breakpoint in a block or in a process. 

Setting a breakpoint in a block means that any process in the block can trip the 

breakpoint and all processes will be intercepted when the breakpoint is reached. 

Setting a breakpoint in a process means that only the specified process can trip 

the breakpoint and only that process will be intercepted. 

A breakpoint is removed when it is reached, i.e. the breakpoint must be set again 

with another set_bp call if it is still needed. 

When a breakpoint is reached, the specified trap signal is sent back to the caller. 

The caller must then free that signal. (The signal may have been copied to a new 

signal buffer by the kernel.) 

If a process or block is killed, breakpoints set in the process/block are cleared. 

Trap signals are freed by the kernel. 

The breakpoint attribute contains CPU-dependent breakpoint modifier bits. These 

are set in combinations to specify various CPU cycles and the like. Bits not used 

should be cleared. 

Only a few attribute bits/values are well defined: 

1. All bits = 0, which identifies a software testpoint. No hardware breakpoint is 

actually set and the breakpoint can thus not be reached. The trap signal is 

returned to the owner whenever intercept status changes in either direction for 

the specified process or for any process in the specified block. The trap signal 

is returned regardless of which event caused the status change. The get_pcb 

call can be used to obtain further information. The address field is in this case 

used only as a breakpoint ID which serves a purpose in a subsequent clear_bp 

call. The address is otherwise not used by the kernel. 

2. Bit 0 selects a pre or post breakpoint. Bit 0=0 means that the process that 

causes the break will stop at the set address. Bit 0=1 means that the process 

will stop one machine instruction beyond the set address. This bit may not be 

valid unless bit 1=1. 

3. Bit 1 selects simple execution breakpoints. Bit 1=1 means that a break will 

occur when the process executes an instruction at the specified address. Bit 

1=0 means that the bit is ignored and other bits determine the breakpoint type. 

Other bits depend on the implementation. 


Parameters pid The ID of the block or process for which the breakpoint is 

set. 


set_bp


Return value 

Restrictions 

See also 

address 

attribute 

trapsig 

The address where the breakpoint is to be set. 

CPU-dependent modifier bits. 

A pointer to the signal buffer returned. 

Returns a non-zero value if the breakpoint could not be set. 

This occurs when either too many breakpoints were set or several breakpoints 

were set at the same address or the attribute contains a value that is not supported. 

In case of error, the trap signal is immediately freed by the kernel. 

Only one breakpoint may be set at each address within a memory segment. This 

is because the address is also used as the breakpoint ID. Implementations may 

find various ways to relax this restriction, but conflicts that can not be handled 

are reported to the caller. 

Breakpoints may not be set in an interrupt or timer-interrupt process. 

The kernel may reallocate the space occupied by the trap signal. Thus, the pointer 

to the trap signal is not valid following the call to set_bp. 

The set_bp call is not available to interrupt processes. 

clear_bp, intercept, resume, get_pcb 



level C. Several aspects of hardware breakpoints are 

implementation-specific. They depend on what is possible in 

the specific processor architecture and target hardware. Only 

attribute = zero must always be supported. 

Example 


#define SIXTH 6 /* These declarations */ 

struct Sixth /* are preferably made */ 



}; 

static const SIGSELECT six[] = {1, SIXTH}; 


void function(void); 

union SIGNAL 

{ 


struct Sixth sixth; 

}; 


{ 


for(;;) 

{ 

trapsignal = alloc(sizeof(struct sixth), SIXTH); 

set_bp(proc_, 


set_bp

} 

} 

(OSADDRESS) function, 

(OSADDRESS) 2, 

&trapsignal); 

trapsignal = receive((SIGSELECT *)six); 

/* Code */ 

free_buf(&trapsignal); 



set_bp

set_env 


Syntax OSBOOLEAN set_env ( PROCESS pid, 

char *name, 

char *value); 

Description Create, update or delete an environment string for the specified process or block. 

The environment variable specified by name is set to the value specified in the 

value parameter. A value set to NULL removes the variable 



name 

A pointer to the enviroment variable name. 

value 

A pointer to the value. 

Return value Returns a non-zero value if out of environment space for the specified process or 

block. 

Restrictions If the specified name or value is longer than the maximum size of a signal buffer, 

then the environment variable is not set. 

The set_env call is not available to interrupt processes. 

See also get_env_list, get_env, get_envp, set_envp 



Example 




{ 

for(;;) 

{ 

set_env(current_process(), "appvar", "xyz21"); 

set_env(proc_, "number", "2000"); 

/* Code */ 

} 

} 


set_env

set_envp 


Syntax OSBOOLEAN set_envp ( PROCESS pid, 

char *name, 

OSADDRESS value); 

Description This system call stores a 32 bit pointer in a named environment variable. The 

value is stored in a special (mangled) format so that it can be efficiently read with 

the get_envp call. 

Variables set with the set_envp call can be read with the get_env call, but the 

string returned is not easily interpreted. 


Parameters pid The ID of the specified block or process. Setting the pid 

parameter to zero is equivalent to using the pid of the current 

process. 

name 

A pointer to the enviroment variable name. 

value 

A pointer to the value. 

Return value Returns a non zero value if the call was successful. Returns zero if the kernel does 

not support the call or if the call failed due to an ignored error report. 

Restrictions Setting a variable to zero is less useful as that value can not be properly read. 

If the specified name is longer than the maximum size of a signal buffer, then the 

environment variable is not set. 

The set_envp call is not available to interrupt processes. 

See also get_env, get_env_list, get_envp, set_env 



Example 



{ 

int prod_data = 0xCAFE; 

OSADDRESS pa; 

for(;;) 

{ 

set_envp(0, "pd", (OSADDRESS)&proc_data); 

pa = get_envp(0, "pd"); 

if (pa != 0) 

printf("pa = %d\n", *(int *)pa); 

/* Code */ 

} 

} 


set_envp

set_fsem 

Syntax 

void set_fsem (OSFSEMVAL value, PROCESS pid); 

Description Initializes a fast semaphore for subsequent use. 


Parameters value The initial value. 

pid 

The ID of the process for which to set the fast semaphore. 


Restrictions The fast semaphore may not be accessed in any way before it is initialized. 

It is illegal to set a fast semaphore to a negative value. 

Some OSE implementations behave badly if a fast semaphore is reinitialized 

while the owner is waiting for it. Portable code should avoid reinitializing fast 

semaphores. 

The set_fsem call is not available to interrupt processes. 

See also signal_fsem, wait_fsem, get_fsem 



Example 





{ 

for(;;) 

{ 

set_fsem((OSSEMVAL) 1, proc_); 

/* Code */ 

} 

} 


set_fsem

set_mem 


Syntax OSBOOLEAN set_mem (PROCESS pid, 

void *from, 

OSADDRESS to, 

OSADDRESS size); 

Description This call is mainly used by memory managers, program loaders and debuggers to 

load and modify a program. 

Writes a specified number of bytes from the address space of the caller to the 

address space of the specified process or block. 



from 

A pointer to the address to read from. 

to 

The address to write to. 

size 

The number of bytes to read. 



Restrictions The caller must be aware of the problems that occur when a program on another 

CPU type is loaded or examined, in particular if that CPU has another word 

length. Link handler conventions should be developed to resolve this. 

The set_mem call is not available to interrupt processes. 

See also get_mem 




set_mem

set_pcb 


Syntax 

OSBOOLEAN set_pcb (PROCESS pid, char *cpuregs); 

Description Sets the CPU registers of the specified process if the process is in a state where 

this is possible. The set_pcb call is mainly used by debuggers. 

Cpuregs contains a string describing the registers to be set. The string format 

corresponds to the format used in the cpuregs string in the get_pcb call, except 

registers may be in any order and not all registers need to be present. 



cpuregs 

A pointer to a string describing the registers. 

Return value Returns zero if the call was successful. 

Returns a non-zero value if the call failed because the process is not in a state 

where the CPU registers can be set, or the string was in a format not recognized. 

Restrictions Works only for prioritized and background processes. 

Implementations are often sensitive to the format of the cpuregs string. For 

example, in an assignment of a CPU register, the number of digits of the register 

value may be crucial for the success of the assignment: "PC=0" may not succeed 

whilst "PC=00000000" would. Take care not to violate the rules provided by each 

implementation. 

The set_pcb call is not available to interrupt processes. 




level C. The set_pcb call is useful only in kernels that provide 

CPU registers per process. 

Example 




{ 

for(;;) 

{ 

/* Code */ 

if(set_pcb(proc_, "A0 = 000037F5")) 

{ 

error(17);/* Set_pcb call was not successful */ 

} 

/* Code */ 

} 

} 


set_pcb

set_pri 

Syntax 

OSPRIORITY set_pri (OSPRIORITY newpri); 

Description Sets a new priority level for the calling process. 

The calling process is moved to the tail of the ready list on the new priority, which 

means that the process is swapped out until all other processes with that priority 

have had an opportunity to execute. 

The newpri parameter may be any priority level allowed in the create_process 

system call. 


Parameters newpri The priority level to set. 

Return value Returns the resulting priority. This is the old priority if the call failed. 

Restrictions Works only for prioritized processes. Some implementations place restrictions on 

how priority levels may be used. 

See also create_process, get_pri, set_pri_for 



Example 




{ 

OSPRIORITY org_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 */ 

} 


{ 

/* Code */ 

/* Reset the original priority */ 

prio = set_pri(org_prio); 

} 

} 

} 


set_pri

set_pri_for 


Syntax 

OSPRIORITY set_pri_for (PROCESS pid, OSPRIORITY newpri); 

Description Sets a new priority level for the specified process. 

The specified process is moved to the tail of the ready list on the new priority, 

which means that the process is swapped out until all other processes with that 

priority have had an opportunity to execute. 

The newpri parameter may be any priority level allowed in the create_process 

system call. 



newpri 

The priority level to set. 

Return value Returns the resulting priority. This is the old priority if the call failed. 

Restrictions Works only for prioritized or background processes. The target process specified 

with the pid parameter must be a prioritized process. Some implementations place 

restrictions on how priority levels may be used. 

See also create_process, get_pri, set_pri 



Example 



{ 

OSPRIORITY org_prio; 


for(;;) 

{ 

org_prio = get_pri(current_process()); 

prio = set_pri_for(current_process(), 31); 

if(prio == org_prio) 

{ 

/* Code, priority could not be set */ 

} 


{ 

/* Code */ 

/* Reset the original priority */ 

prio = set_pri(org_prio); 

} 

} 

} 


set_pri_for


Syntax 

Description 

void set_redirection (PROCESS pid, struct OS_redir_entry *redir); 


The redir parameter is a pointer to a redirection table that describes how signals 

sent to the process pointed out by the pid parameter should be redirected. The 

redirection table contains an array of signal/process pairs. When a signal is sent 

to the process, the redirection table is searched and if present in the table, the 

signal is redirected to the process that should receive the signal. 

The redirection table consists of an array of structures of type "struct 

OS_redir_entry", which is defined as: 

struct OS_redir_entry 

{ 

SIGSELECT sig; 

PROCESS pid; 

}; 


The first structure in the redirection table contains a count of the number of 

entries in the table including the first entry, and a process ID to which signals not 

specified in the redirection table should be sent. The count is always at least 1, 

and the default process ID may be set to zero to specify the process to wich the 

redirection table is attached. 

The kernel may or may not copy this table to kernel memory, so the user must 

assume that the table can not be subsequently altered. 



redir_table A pointer to the redirection table. 


Restrictions The redirection table must be built in run-time since process identities are 

unknown at compile time. 

The set_redirection call is not available to interrupt processes. 

See also create_process 




set_redirection

Example 


#define REDIRECTED_SIG 0xCAFE 


void redir_to_proc(void) 

{ 

OS_redir_entry redir_tbl[2]; 

/* Set number of entries in the redir table */ 

redir_tbl[0].sig = 2; 

/* Set default addressee for signals not found in the redir table. 

* If we set this to zero we mean that the default addressee will 

* be set to the process pointed out by the pid parameter when 

* calling set_redirection(). 

*/ 

redir_tbl[0].pid = 0; 

/* State that if REDIRECTED_SIG is sent it should be directed 

* to new_proc_ instead. 

*/ 

redir_tbl[1].sig = REDIRECTED_SIG; 

redir_tbl[1].pid = proc_; 


/* Set the redirection table for the current process */ 

set_redirection(current_process(), redir_tbl); 

} 


set_redirection

set_segment 


Syntax OSBOOLEAN set_segment (OSBOOLEAN go_home, 

OSSEGMENT segnum); 


therefore not a user system call. 

This call sets the effective segment number for the calling process. 

This ID is provided by the kernel in subsequent select_segment calls to the MMU, 

and a select_segment call is immediately issued from within the set_segment call. 

The real segment ID, once set with attach_segment, is not affected. The real 

segment ID is always the "home" segment of the process. 

The segment selected is locked to the calling process so that the segment can not 

disappear until another segment is set, or the process is killed. 

The home segment is reselected by setting the go_home flag to a non-zero value, 

in which case the segnum parameter is ignored. 

The intention is that the set_segment call should be used from within mem_move 

to temporarily select segments while performing intersegment copying. When 

copying is complete, the home segment is reselected by calling set_segment with 

the go_home flag set. 


Parameters go_home 

segnum 

Return value Set_segment returns non-zero if the segment does not exist, which occurs if the 

segment died before it could be locked by set_segment. 

Restrictions The set_segment function can only be called by a process executing in supervisor 

space. The set_segment call is not available to interrupt processes. 

See also mem_move, select_segment, attach_segment 

Implementation Not implemented at levels A, B and C. Full performance at 

levels level D. 


set_segment



Syntax OSBOOLEAN set_segment_mode (OSSEGMENT segnum, 

OSBOOLEAN contains_int); 

Description This is a call from the kernel to the memory manager block and is therefore not 

a user system call. 

If contains_int is non-zero: 

The kernel tells the MMU that the specified segment contains at least one 

interrupt process, timer-interrupt process or a prioritized process with a priority 

high enough to disallow paging/swapping.This means that the MMU must make 

the entire memory segment resident. (Page faults are fatal if they occur in an 

interrupt or timer-interrupt process.) The call must not return until memory has 

been made resident. 

If contains_int is zero: 

The kernel tells the MMU that all interrupt and timer-interrupt processes in the 

memory segment have been killed, and paging/swapping may be re-enabled. This 

is the initial state assumed by the MMU software. 

The set_segment_mode function may use system calls as if it was called from a 

prioritized superuser process. It is called in the context of a system daemon, so 

the set_segment function can be simultaneously executed by several processes, but 

the calling process can not be killed. 

Any alloc calls issued by the attach_block function refer to the system pool, and 

the caller is a superuser process. 


Parameters segnum 

contains_int 

Return value Zero if ok, nonzero if out of ram. 


See also attach_block, attach_segment, mem_move 

Implementation Not implemented at levels A, B and C. Full performance 

levels from level D. 


set_segment_mode

set_sigsize 

Syntax 

Description 

OSBOOLEAN set_sigsize (union SIGNAL **sig, OSBUFSIZE newsize); 

This system call attempts to change the size of a signal buffer without actually 

reallocate and copy it. This can only be done if the requested size is smaller than 

the actual size of the buffer. 


or 



newsize 

The requested new size of the buffer. 

Return value 

Restrictions 

See also 

Returns a non zero value if the operation was successful. Returns zero if the 

operation failed. 

None. 

alloc, sigsize 



Example 




union SIGNAL 

{ 


}; 


{ 


union SIGNAL *sig2; 

OSBUFSIZE size; 

for(;;) 

{ 


if (set_sigsize(&sig, sigsize(&sig) + 4)) 

{ 

/* Successfully enlarged the signal */ 

} 


{ 

/* Could not enlarge the signal */ 

} 

/* Code */ 

} 

} 


set_sigsize

set_suid 


Syntax 

Description 

Include files 

Parameters 

Return value 

Restrictions 

void set_suid (OSBOOLEAN make_super); 

This is a call used to implement non-OSE system calls, and is therefore not a user 

system call. 

The set_suid system call temporarily assigns superuser (user 0) privileges to the 

calling process. This allows the caller to communicate with processes normally 

invisible to the calling process. 

The calling process is also temporarily attached to the system pool, i.e. any alloc 

calls issued while in a superuser region refers to the system pool, regardless of 

the pool normally attached to the calling process. 

The kernel maintains a record of how many times a process has acquired 

superuser rights with a non-zero set_suid parameter. A process relinquishes 

superuser rights only when the same number of set_suid calls with a zero 

parameter have been issued. 

The intention is to allow users to provide a level of application specific operating 

system services that appear as system calls. Any user or supervisor mode process 

may trap to one of these services. The service uses the set_suid call with a nonzero 

parameter to acquire superuser rights, communicates with system processes, 

and then uses the set_suid call with a zero parameter to restore non-superuser 

rights before returning to the caller. 


make_super 

None. 

The set_suid function can only be called by a process executing in supervisor 

mode. There is, however, no restriction on the user number of the process. A nonsuperuser 

process may thus access the set_suid while executing in supervisor 

mode. 

The set_suid call is not available to interrupt processes. 

Implementation Not implemented at levels A, and B. Full performance at 

levels level C and D. 


set_suid

sigsize 

Syntax 

Description 

OSBUFSIZE sigsize (union SIGNAL **sig); 

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

was allocated. 


or 



Return value Returns the number of bytes requested when the buffer was allocated. 


See also alloc, set_sigsize 



Example 




union SIGNAL 

{ 


}; 


{ 


union SIGNAL *sig2; 

OSBUFSIZE size; 

for(;;) 

{ 


size = sigsize(&sig); 

sig2 = alloc(size,sig->sig_no); 

/* Code */ 

} 

} 


sigsize

signal_fsem 


Syntax 

Description 

void signal_fsem (PROCESS pid); 

Increments the value of the fast semaphore associated with the specified process. 

If the result is zero, the specified process is made ready if it had done a wait_fsem. 

If the process is an interrupt process, a wake_up invocation of the process is 

scheduled. 


or 


Parameters pid The ID of the process for which the fast semaphore is 

signalled. 


Restrictions 

See also 

It is illegal to cause a fast semaphore to wrap from high positive numbers to a 

negative value for all processes but interrupt processes (these are allowed to wrap 

since the fast semaphore is only used to issue a wake_up call). 

Signal_fsem may be called also from interrupt and timer-interrupt processes, but 

it is an error to cause a remote system call while doing so, i.e. an interrupt or 

timer-interrupt process may not access a fast semaphore in another CPU. 

set_fsem, wait_fsem, get_fsem 



Example 




{ 

for(;;) 

{ 

/* Code */ 

signal_fsem(proc_); 

/* Code */ 

} 

} 


signal_fsem

signal_sem 

Syntax 

Description 

void signal_sem (SEMAPHORE *sem); 

Increments the value of the specified semaphore and releases the first process 

waiting at the semaphore. 


or 


Parameters sem A pointer to the semaphore to be signalled. 


Restrictions 

See also 

It is illegal to cause a semaphore to wrap from high positive numbers to a negative 

value. 

wait_sem, get_sem, create_sem, kill_sem 



Example 


extern SEMAPHORE *sem; 



{ 

for(;;) 

{ 

/* Code */ 

signal_sem(sem); 

/* Code */ 

} 

} 


signal_sem

start 


Syntax 

Description 

void start (PROCESS pid); 

Starts a previously stopped or newly created block or process. 

The kernel keeps a record of how many times each process has been stopped. A 

process is allowed to execute again only when the same number of start calls have 

been issued. 

Each new process must be started to enable execution. 

Starting a block is equivalent to issuing a start call to each of the processes 

contained in the block. It is important that no process is started individually before 

the block is started, since starting a process twice is illegal. 

Starting a timer-interrupt process means that it from now on will be scheduled to 

run at its specified time interval. 


or 


Parameters pid The ID of the block or process to start. 


Restrictions 

See also 

Only prioritized, background and timer-interrupt processes can be stopped. The 

start and stop calls have no effect on process types that can not be stopped. 

Starting a process that is not stopped is illegal. (It is illegal to start a process more 

times than it was stopped.) 

This implies that it is always illegal to start the current process or the current 

block. 

Start may be called also from interrupt and timer-interrupt processes, but it is an 

error to cause a remote system call while doing so, i.e. an interrupt or timerinterrupt 

process may not start a process in another CPU, and the kernel ignores 

any attempt to do so. 

stop, create_process 



Example 




{ 

PROCESS proc1_; 

PROCESS proc2_; 


for(;;) 

{ 


start


} 

} 

proc1_ = create_process(OS_PRI_PROC, 

"proc1", 

new_process, 

200, 

16, 

(OSTIME) 0, 

(PROCESS) 0, 


(OSVECTOR) 0, 

(OSUSER) 0); 

start(proc1_); 


(OSUSER) 0, 


(PROCESS) 0, 


proc2_ = create_process(OS_PRI_PROC, 

"proc2", 

new_process, 

200, 

16, 

(OSTIME) 0, 

block_, 


(OSVECTOR) 0, 

(OSUSER) 0); 

start(block_); 

/* Code */ 


start

start_OSE 


Syntax 

Description 

Include files 

Parameters 

Return value 

Restrictions 

void start_OSE (void); 

This function works in two ways. 

start_OSE is called during system start to create the kernel and initialize kernel 

structures. 

This function does not return to the caller since the kernel replaces the caller's 

program. 

start_OSE is also called by the main process for each separately linked OSE unit 

to create the static blocks and processes contained in that unit. 

The main process does not return. It waits in the interface library for any static 

process to die, and then kills all blocks in the unit. This behaviour relies on the 

convention that program loaders keep track of the main process, and kill the 

memory segment when the main process dies. Other conventions are possible and 

may appear in certain systems. 

It might be possible to restert the system by calling start_OSE in a running 

system. 


None. 

None. 

Kernels that do not support user initiated system start need not provide the 

start_OSE call. 

The start_OSE call is not available to interrupt processes. 



Example 


int main() 

{ 

/* Code, initialisation etc. */ 

start_OSE(); 

} 


start_OSE

stop 


Syntax 

Description 

void stop (PROCESS pid); 

Suspends the execution of a single process or all processes in a block. 

It is legal to stop a process any (reasonable) number of times. 

The kernel keeps a record of how many times each process has been stopped. A 

process is allowed to execute again only when the same number of start calls have 

been issued. 

Stopping a block is equivalent to issuing a stop call to each of the processes 

contained in the block. 

Stopping a timer-interrupt process means that it will no longer be scheduled to 

run at its specified time interval. 


or 


Parameters pid The ID of the block or process to stop. 


Restrictions 

See also 

Only prioritized, background and timer-interrupt processes can be stopped. The 

start and stop calls have no effect on process types that can not be stopped. 

Stop may be called also from interrupt and timer-interrupt processes, but it is an 

error to cause a remote system call while doing so, i.e. an interrupt or timerinterrupt 

process may not stop a process in another CPU, and the kernel ignores 

any attempt to do so. 

Note that a timer-interrupt process will continue to execute until its end, even after 

issuing a stop(current_process()), but it will no longer be scheduled to run at its 

specified time interval. 

start 



Example 




{ 

for(;;) 

{ 

stop(proc_); 

/* Code */ 

start(proc_); 

} 

} 


stop

system_tick 

Syntax 

Description 

Include files 

Parameters 

Return value 

Restrictions 

See also 

OSTIME system_tick (void); 



or 


None. 

Returns the number of microseconds per system tick. 

This call relies on the tick system call being issued at intervals corresponding to 

the system tick length configured into the kernel. This can not be ensured by the 

kernel itself. 

SYSTEM_TICK, tick 



Example 




{ 

unsigned int tick; 

for(;;) 

{ 

/* Code */ 

tick = system_tick(); 

/* Code */ 

} 

} 


system_tick

tick 


Syntax 

Description 

Include files 

Parameters 

Return value 

Restrictions 

void tick (void); 

This call advances the system clock. 

The system tick counter is advanced, timer-interrupt processes are invoked, 

process timeslices and timeouts requested by calls to delay, receive_w_tmo et al. 

are managed. 

Timer-interrupt processes are run at the priority of the calling interrupt process, 

or at a priority immediately below interrupt processes if tick was called from a 

prioritized process. 


or 


None. 

None. 

Tick should be called periodically at intervals that match the value returned by 

system_tick (). 

Tick may not be called from a timer-interrupt process. 

Tick may only be called from a superuser process executing in supervisor space. 

The tick system call is not re-entrant. Only one process in the system may call 

tick. 

It may be required to the state the type of the calling process and hardware 

priority in the kernel configuration file.Wakeup calls may otherwise be hard to 

implement. 

Kernels with built in timer management need not provide the tick system call. 

Implementation Not implemented at level A, but the kernel is still required levelsto manage the 

system timer in some fashion. Full 

performance from level B. 

Example 


OS_PROCESS(ticker) 

{ 

if(wake_up()) /* This is an interrupt process */ 

{ /* used as a timer. */ 

tick(); /* Its only function is to run the */ 

} /* system clock. */ 

} 


tick

wait_fsem 


Syntax 

void wait_fsem (OSFSEMVAL count); 

Description Waits at the fast semaphore associated with the caller. 

The semaphore value is decreased by the specified amount. If the result is 

negative, the caller is suspended until some other process has issued enough 

signal_fsem calls for the value to become non-negative. 


Parameters count The number to decrease the fast semaphore with. 


Restrictions The wait_fsem call is not available to interrupt processes, but fast semaphores 

may still be used in a limited fashion to wake up interrupt processes from 

prioritized processes. 

This may be used for instance to start a sequence that is mainly interrupt driven, 

such as transmitting a string of characters to some serial port. 

See also signal_fsem, get_fsem, set_fsem 



Example 



{ 

for(;;) 

{ 

/* Code */ 

wait_fsem((OSFSEMVAL) 1); 

/* Code */ 

} 

} 


wait_fsem

wait_sem 

Syntax 

void wait_sem (SEMAPHORE *sem); 

Description The caller waits at the specified semaphore structure. 

The semaphore value is decremented. If the result is negative, the caller is 

suspended and queued at the end of the semaphore queue. 

Each time some other process signals the semaphore, the value is incremented and 

the first process queued at the semaphore is released. 


Parameters sem A pointer to the semaphore. 


Restrictions The wait_sem call is not available to interrupt processes. 

See also signal_sem, get_sem, create_sem, kill_sem 



Example 





{ 

for(;;) 

{ 

/* Code */ 

wait_sem(sem); 

/* Code */ 

} 

} 


wait_sem

wake_up 


Syntax 

Description 

Include files 

Parameters 

Return value 

int wake_up (void); 

An interrupt process can be invoked in two ways; either by a hardware interrupt 

or by a software event. In both cases the interrupt process is invoked with 

interrupts disabled up 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 

invoked. This is useful because receive calls are fairly expensive and can often not 

be afforded at each hardware interrupt. 

Software events that cause interrupt processes to be invoked are signal 

transmissions to an interrupt process and signal_fsem calls specifying an interrupt 

process. 

Hardware interrupts are delayed until the wake_up call has completed. 


or 


None. 

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 is ready to be fetched with a receive call. 

Returns 2 if the interrupt process was invoked in response to a signal_fsem call 

issued by some other process. (The value of the fast semaphore is not important 

and can not be read with the get_fsem system call.) 

If called by a process of a type other than an interrupt process, the wake_up 

function returns 1 (one). 

Restrictions Some processors can not accept a simulated interrupt call. 

On these processors it may not be possible to implement the wake_up feature, or 

there may be some restrictions. A common problem is that nested interrupts must 

be disabled while a wake_up call is in progress. 



Example 


union SIGNAL 

{ 


}; 

OS_PROCESS(my_interrupt_process) 

{ 

static const SIGSELECT all[] = {0}; 



wake_up

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); 


break; 

case 2: 

/* signal_fsem() on this process caused the wake_up */ 

break; 

default: 

/* this is an error */ 

} 

} 



wake_up

NIL 


Syntax 

Description 

Include files 

Return value 

Restrictions 

#define NIL 

NIL is a manifest constant defined by the kernel. It is defined in ose.h and in 

ose_i.h. 

NIL is the value returned from receive, receive_w_tmo and receive_from when no 

signal buffer could be received. 

NIL is stored in the caller's signal pointer by the send, send_w_s and free_buf 

system calls. 

NIL is not equivalent to NULL, and should be used only to test on received 

buffers. 


or 


None. 

NIL is specified such that it is never confused with a legal signal pointer. 

Furthermore, it is an advantage if NIL points to a valid scratchpad area. This 

enables the kernel to correctly report several user errors that would otherwise lead 

to bus error or memory parity error. 



Example 



union SIGNAL 

{ 


}; 


{ 


for(;;) 

{ 

sig = receive_w_tmo(1000, (SIGSELECT *)any_sig); 


{ 

/* Code */ 


} 

} 

} 


NIL

OS68 


Syntax 

Description 

Include files 

Return value 

Restrictions 

See also 

#define OS68 

A CPU dependent manifest constant of similar layout is defined by the header 

files ose.h and ose_i.h. 

The value of this constant is unimportant. It is intended for use in an #ifdef or 

#ifndef statement. 

It may be used by an application or an OSE system simulator to determine which 


softOSE means a that the OSE system is a soft kernel. 

OSPP means OSE for any PowerPC CPU. 

OS68 means OSE for any Motorola 68k CPU, 

OS88 means OSE for the Motorola 88000 CPU, 

OS11 means OSE for the Motorola 68HC11 CPU, etc. 


or 


None. 

None. 

OSE_I, OSE 



Example 


OSPROCESS(my_process) 

{ 

for(;;) 

{ 

#ifdef OS68 

/* Code */ 

#else 

/* Code */ 

#endif 

} 

} 


OS68

OS_ATTACH_SIG 

Syntax #define OS_ATTACH_SIG 252 

Description 

Include files 

Return value 

Restrictions 

See also 

A manifest constant defining the signal number of the default signal created by 

the attach system call when invoked with a signal pointer set to NULL. 

It is defined in the header files ose.h and ose_i.h. 

It may be used by an application to determine if such a signal was received. 

The value of this constant is always 252. 


or 


None. 

None. 

attach, detach 



Example 




union SIGNAL 

{ 


}; 


{ 


for(;;) 

{ 


switch(sig->sig_no) 

{ 

case OSATTACH_SIG: 

/* Code */ 

break; 

default: 

/* Code */ 

} 


} 

} 


OS_ATTACH_SIG

OS_DEBUG 


Syntax 

Description 

Include files 

Return value 

Restrictions 

See also 

#define OS_DEBUG 

This manifest constant may be defined by the user to enable reporting of file and 

line information and CPU registers to the debugger. 



The constant affects the header files ose.h, ose_i.h. 

OS_DEBUG is typically defined on the compiler command line to enable file and 

line information and CPU registers in a specific module. 


or 


None. 

OS_DEBUG must be defined before any OSE header is included. 

File and line information, as well as CPU register information, is optional to the 

OSE implementation. This means that some implementations lack all or parts of 

this information. 

get_pcb 



Example 

The typical way to define the constant is as a compiler directive, for instance in a make file as 

follows: 

CFLAGS= -c -g -Wall -ansi -pedantic -DOS_DEBUG -I. 

It may also be declared in a define statement: 

#define OS_DEBUG 


OSPROCESS(my_process) 

{ 

for(;;) 

{ 

#ifdef OS_DEBUG 

/* Code */ 


/* Code */ 

#endif 

} 

} 


OS_DEBUG

OSE 

Syntax 

Description 

Include files 

Return value 

Restrictions 

See also 

#define OSE 

This manifest constant is defined by ose.h. 



It may be used by an application or an OSE system simulator to find out which 

OSE header file is being used. 


None. 

The OSE manifest constant is not available to interrupt processes. 

OSE_I, OS68 



Example 




{ 

#ifdef OSE 

for(;;) 

{ 

/* Code, "I am a prioritized process" */ 

} 


if(wake_up()) 

{ 

/* Code, "I am an interrupt process" */ 

} 

#endif 

} 


OSE

OSE_LEVEL_x 


Syntax 

#define OSE_LEVEL_B 

#define OSE_LEVEL_C 

#define OSE_LEVEL_D 

Description These manifest constants are defined in ose.h and ose_i.h. 

They may be used by an application or an OSE system simulator to find out the 

functional level of the kernel used. 

Each constant represents a fully supported OSE implementation level. 

OSE_LEVEL_B is defined if at least level B is supported. 

OSE_LEVEL_C is defined if at least level C is supported. 

OSE_LEVEL_D is defined if level D is supported. 

The values of the constants are unimportant. They are intended for use in #ifdef 

or #ifndef statements. 

All constants below the actual implementation level are defined. For instance, a 

level C implementation defines both OSE_LEVEL_B and OSE_LEVEL_C, but 

not OSE_LEVEL_D. 


or 






Example 



{ 

for(;;) 

{ 

#ifdef OSE_LEVEL_B 

/* Code */ 

#endif 

#ifdef OSE_LEVEL_C 

/* Code */ 

#endif 

#ifdef OSE_LEVEL_D 

/* Code */ 

#endif 

} 

} 


OSE_LEVEL_x

OSE_I 

Syntax 

Description 

Include files 

Return value 

Restrictions 

See also 

#define OSE_I 

Same as OSE, but defined in ose_i.h. 


None. 

The OSE_I manifest constant is only available to interrupt processes. 

OSE, OS68 



Example 




{ 

for(;;) 

{ 

#ifdef OSE_I 

if(wake_up()) 

{ 

/* Code, "I am an interrupt process" */ 

} 


for(;;) 

{ 

/* Code, "I am a prioritized process" */ 

} 

#endif 

} 


OSE_I

OS_PROCESS 

Syntax 

#define OS_PROCESS (name) 

Description This macro should be used to define the entrypoint of a process. 

It is defined in ose.h and ose_i.h. 

Various OSE implementations use this macro in different ways. 

It is wise to assume that OS_PROCESS is differently defined in ose.h and ose_i.h, 

even if this is not normally the case. 


or 






Example 




{ 

for(;;) 

{ 

/* Code */ 

} 

} 


OS_PROCESS

OSSIM 


Syntax 

#define OSSIM 

Description The user should define this manifest constant when compiling a process for use 

in the OSE system simulator. 



The header files ose.h and ose_i.h test on this constant and replace themselves 

with ossim.h if OSSIM is defined. ossim.h is part of the OSE simulator. 

The header file ose_mmu.h test on this constant and replaces itself with 

sim_mmu.h if OSSIM is defined. The file sim_mmu.h is part of the OSE 

simulator. 

The constants OSE, OSE_I and OS68 are defined before the test on OSSIM, so 

these constants can be interrogated by ossim.h. 

It may sometimes be desirable to test on OSSIM in user programs too. For 

instance one may wish to remove target dependent code that can not cooperate 

with the OSE simulator. 


or 



Restrictions OSSIM must be defined before any OSE header is included. 



Example 

The most common way to use OSSIM is as a flag in a make file as in example 1. 

It can then be used in the application code as in example 2. 

Example 1 

CFLAGS= -c -g -Wall -ansi -pedantic -DOSSIM -I./ 

#generalized rules 

.c.o: 

gcc $(CFLAGS) -o $@ $< 

# the makefile continues 

Example 2 



{ 

for(;;) 

{ 

/* Code */ 

#ifdef OSSIM 

/* Code */ 



OSSIM

#endif 

} 

} 

/* Code that is target dependent and can not run 

* in the simulator. 

*/ 

/* Code */ 



OSSIM

SYSTEM_TICK 

Syntax 

#define SYSTEM_TICK (1000L) 

Description This manifest constant is always 1000L. 

It is present only for compatibility with old OSE kernels (it should not be used 

when writing applications for OSE), where the delay and receive_w_tmo calls 

specify timeout in number of system ticks instead of in number of milliseconds. 

An old way of saying "delay 50 milliseconds" is: 

delay((OSTIME) ((50 * 1000L) / SYSTEM_TICK)); 


This design also works with new OSE versions since the SYSTEM_TICK 

constant balances the expression. 

(It is, of course, more efficient to calculate the expression in advance and save the 

result for repeated use.) 


or 




See also system_tick, delay, receive_w_tmo 




SYSTEM_TICK

4 User Interface 

4.1 Header Files 

The user interface to OSE is defined in a number of C header 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, and the OSSIM constant indicates that code should 

be produced for an OSE simulator session. 

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. 


The following standard headers define the OSE interface: 

ose.h 

System calls for prioritized processes and background processes. This header is used in most 

applications. 

ose_i.h 

System calls for interrupt processes and timer-interrupt processes. This header is used in most 

applications. 

ose_rem.h 

Remote call format for link handlers. This is actually a signal definition file. This header requires 

ose.h and will not work with ose_i.h. This header is used only in link handlers and remote call 

servers. 

ose_mmu.h 

Prototypes for functions that must be provided by user-written memory management software. This 

header file defines the functions attach_block, select_segment, set_segment_mode and mem_move. 

See also the detailed system call description for these calls. Using the ose_mmu header requires 

ose.h to be included as well. It will not work with ose_i.h. This header is used only in memory 

management software and the header is therefore present only in level C and D implementations. 

ose_err.h 

Error code definitions for error handlers. This header is used only in error handlers and defines 

symbolically the error codes provided by the OSE kernel when the kernel detects an error. 

When using these files the "union SIGNAL" type must be defined. This must be done after the 

header files have been included and the union must consist of all signals used in the particular file. 

For a more detailed description refer to the section on OSE Data Types. 


User Interface

ose.h, ose_i.h and ose_mmu.h test on the manifest constant OSSIM. This constant causes the 

headers ose.h and ose_i.h to replace themselves with ossim.h, and ose_mmu.h to replace itself with 

sim_mmu.h. 

Many OSE system calls are in fact implemented as macros. This means that when writing an 

application it is important to be aware of this since it results in limitations on how system calls can 

be used. 



User Interface

4.2 Data Types 

The 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 "signals.sig" 


union SIGNAL 

{ 

SIGSELECT 

struct First 

struct Testsignal 

}; 

sig_no; 

first; 

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 like this: 


User Interface

#define FIRST 1 

struct First 

{ 


/* Here, other data can be declared if desirable 

* for instance: char data; 

*/ 

}; 


The following is a list of types with usage information: 

Type 

Usage 

union SIGNAL 

A signal structure 

SIGSELECT 

A signal number 

PROCESS 

A process ID 

OSBUFSIZE 

The number of bytes in a signal 

OSPRIORITY 

A process priority 

OSUSER 

A user number 

OSFSEMVAL 

A fast semaphore value 

OSSEMVAL 

A semaphore value 

OSSERCODE 

Information passed to error() 

OSADDRESS 

A memory address 

OSENTRYPOINT 

A process entrypoint 

OSTIME 

Used by delay() and similar 

OSTICK 

Returned from get_ticks() 

OSVECTOR 

An interrupt vector number 

SEMAPHORE 

A semaphore structure 

OSBOOLEAN 

A binary flag 

OSSEGMENT 

A segment ID used by MMU 

OSATTREF 

An attach reference ID 

OSERRH 

An error handler entrypoint 

enum PROCESS_TYPE The type of a process 

enum PROCESS_STATUS The status of a process 

struct semaphore 

A semaphore field 

struct OS_redir_entry A redirection table field 


A process ID list 

struct OS_pcb 

Miscellaneous process information 


User Interface

5 Remote System Calls 

There are a number of system calls that may operate on blocks and processes in other CPUs. If a 

process issues one of these calls to a process not present in the same CPU, the OSE kernel translates 

the system call into a remote system call. Remote system calls are signal transactions which are 

executed by the OSE kernel. The OSE kernel sends a remote_call signal to the remote call server 

attached to the specified process (usually a phantom process). This remote call server is often a link 

handler. 


5.1 Signal Definitions 

The OSE kernel defines three signals for remote calls; remote_call, remote_response and 

remote_cancel. 

Each system call consists of a remote_call signal in the forward direction, and either a 

remote_response or a remote_cancel signal in the return direction. In the remote_response signal the 

response is returned from the remote call server to OSE. 

A remote_cancel signal may be returned if the remote call server cannot execute the remote system 

call. In that case OSE aborts the system call and produces a reasonable dummy result. Valid reasons 

for this are if the contact with the remote system is lost or if the requested system call is not 

recognized by the remote call server. 

These signals and associated unions and manifest constants are defined in the header file ose_rem.h. 

The signal numbers for these three signals are reserved and should not be used for any other purpose 

by a link handler. 

The call_type field in the remote_call and remote_response signals indicates which system call is 

being executed. It is also used to select members of the remote_calls and remote_responses unions 

respectively. 

When these signals are propagated to a foreign system on the network, they should be transformed 

to a set of packets specified at byte level to support transmission between systems with different byte 

order and type conventions. OSE ensures that signal buffers received by a link handler can be used 

without reallocation to return responses for the same system call. This is true for all system calls 

except those with variable size responses. 

The three signal structures are listed below: 

#define REMOTE_CALL (255) 

struct remote_call 

{ 


OSCALLTYPE call_type; 

union remote_calls params; 

}; 

#define REMOTE_RESPONSE (254) 

struct remote_response 

{ 



Remote System Calls

OSCALLTYPE call_type; 

union remote_responses results; 

}; 

#define REMOTE_CANCEL (253) 

struct remote_cancel 

{ 


}; 

The remote_calls and remote _responses unions are listed below: 


union remote_calls 

{ 

struct rem_clear_bp rem_clear_bp; 

struct rem_create_error_handler rem_create_error_handler; 

struct rem_flush rem_flush; 

struct rem_get_cpu rem_get_cpu; 

struct rem_get_env rem_get_env; 

struct rem_get_env_list rem_get_env_list; 

struct rem_get_fsem rem_get_fsem; 

struct rem_get_mem rem_get_mem; 

struct rem_get_pcb rem_get_pcb; 

struct rem_get_pid_list rem_get_pid_list; 

struct rem_get_pri rem_get_pri; 

struct rem_get_signal rem_get_signal; 

struct rem_get_uid rem_get_uid; 

struct rem_hunt rem_hunt; 

struct rem_intercept rem_intercept; 

struct rem_resume rem_resume; 

struct rem_set_bp rem_set_bp; 

struct rem_set_env rem_set_env; 

struct rem_set_fsem rem_set_fsem; 

struct rem_set_mem rem_set_mem; 

struct rem_set_pcb rem_set_pcb; 

struct rem_signal_fsem rem_signal_fsem; 

struct rem_start rem_start; 

struct rem_stop rem_stop; 

}; 

union remote_responses 

{ 

struct remr_clear_bp remr_clear_bp; 

struct remr_create_error_handler remr_create_error_handler; 

struct remr_get_cpu remr_get_cpu; 

struct remr_get_env remr_get_env; 

struct remr_get_env_list remr_get_env_list; 

struct remr_get_fsem remr_get_fsem; 

struct remr_get_mem remr_get_mem; 

struct remr_get_pcb remr_get_pcb; 

struct remr_get_pid_list remr_get_pid_list; 

struct remr_get_pri remr_get_pri; 

struct remr_get_signal remr_get_signal; 

struct remr_get_uid remr_get_uid; 

struct remr_hunt remr_hunt; 

struct remr_set_bp remr_set_bp; 

struct remr_set_env remr_set_env; 

struct remr_set_mem remr_set_mem; 

struct remr_set_pcb remr_set_pcb; 

}; 


Remote System Calls

The call_type field contains one of the following values 

#define REM_CLEAR_BP 1 

#define REM_CREATE_ERROR_HANDLER 2 

#define REM_FLUSH 3 

#define REM_GET_CPU 4 

#define REM_GET_ENV 5 

#define REM_GET_ENV_LIST 6 

#define REM_GET_FSEM 7 

#define REM_GET_MEM 8 

#define REM_GET_PCB 9 

#define REM_GET_PID_LIST 10 

#define REM_GET_PRI 11 

#define REM_GET_SIGNAL 12 

#define REM_GET_UID 13 

#define REM_HUNT 14 

#define REM_INTERCEPT 15 

#define REM_RESUME 16 

#define REM_SET_BP 17 

#define REM_SET_ENV 18 

#define REM_SET_FSEM 19 

#define REM_SET_MEM 20 

#define REM_SIGNAL_FSEM 21 

#define REM_START 22 

#define REM_STOP 23 

#define REM_SET_PCB 24 


#define REMR_CLEAR_BP 1 

#define REMR_CREATE_ERROR_HANDLER 2 

#define REMR_FLUSH 3 

#define REMR_GET_CPU 4 

#define REMR_GET_ENV 5 

#define REMR_GET_ENV_LIST 6 

#define REMR_GET_FSEM 7 

#define REMR_GET_MEM 8 

#define REMR_GET_PCB 9 

#define REMR_GET_PID_LIST 10 

#define REMR_GET_PRI 11 

#define REMR_GET_SIGNAL 12 

#define REMR_GET_UID 13 

#define REMR_HUNT 14 

#define REMR_INTERCEPT 15 

#define REMR_RESUME 16 

#define REMR_SET_BP 17 

#define REMR_SET_ENV 18 

#define REMR_SET_FSEM 19 

#define REMR_SET_MEM 20 

#define REMR_SIGNAL_FSEM 21 

#define REMR_START 22 

#define REMR_STOP 23 

#define REMR_SET_PCB 24 


Remote System Calls

5.2 Parameter Structures 

This section defines the members of the remote_calls and remote_responses unions. 

Remote call servers must be able to handle all of these and produce reasonable responses. 

Some remote call responses consist only of a signal number and a call_type parameter. There is no 

response structure defined for these calls. 

rem_clear_bp 

Include files 

remote_calls member 

remote_responses member 

#include "ose_rem.h" 

struct rem_clear_bp 

{ 

PROCESS pid; 

OSADDRESS addr; 

}; 

struct remr_clear_bp 

{ 

OSBOOLEAN failed; 

}; 


rem_create_error_handler 

Include files 




struct rem_create_error_handler 

{ 

PROCESS pid; 

OSADDRESS entrypoint; 

OSADDRESS stacksize; 

}; 

struct remr_create_error_handler 

{ 

OSADDRESS entrypoint; 

}; 

rem_flush 

Include files 




struct rem_flush 

{ 

PROCESS pid; 

PROCESS psel[1]; /* Variable size */ 

}; 

None. 


rem_clear_bp

em_get_cpu 

Include files 




struct rem_get_cpu 

{ 

PROCESS pid; 

}; 

struct remr_get_cpu 

{ 

char name[1]; /* Variable size */ 

}; 

rem_get_env 


Include files 



rem_get_env_list 

Include files 




struct rem_get_env 

{ 

PROCESS pid; 


}; 

struct remr_get_env 

{ 

char value[1]; /* Variable size */ 

}; 


struct rem_get_env_list 

{ 

PROCESS pid; 

char first_name[1]; /* Variable size */ 

}; 

struct remr_get_env_list 

{ 


}; 


rem_get_cpu

em_get_fsem 

Include files 




struct rem_get_fsem 

{ 

PROCESS pid; 

}; 

struct remr_get_fsem 

{ 

OSFSEMVAL value; 

}; 

rem_get_mem 


Include files 



rem_get_pcb 


struct rem_get_mem 

{ 

PROCESS pid; 

OSADDRESS from; 

void * to; 

OSADDRESS size; 

}; 

struct remr_get_mem 

{ 


}; 

Include files 




struct rem_get_pcb 

{ 

PROCESS pid; 

}; 

struct remr_get_pcb 

{ 

struct OS_pcb pcb; /* Variable size */ 

}; 


rem_get_fsem

em_get_pid_list 

Include files 




struct rem_get_pid_list 

{ 

PROCESS bid; 

}; 

struct remr_get_pid_list 

{ 


PROCESS pidlist[1]; /* Variable size */ 

}; 

rem_get_pri 


Include files 




struct rem_get_pri 

{ 

PROCESS pid; 

}; 

struct remr_get_pri 

{ 

OSPRIORITY pri; 

}; 


rem_get_pid_list

em_get_signal 

Include files 



{ 

}; 


struct rem_get_signal 

{ 

PROCESS pid; 

OSADDRESS mailptr; 

}; 

struct remr_get_signal 

OSADDRESS nextsig; 

OSBUFSIZE sigsize; 

/* Zero if call 

* failed 

*/ 

PROCESS sender; 

PROCESS addressee; 

unsigned char contents[1]; 

/* Variablesize */ 


rem_get_uid 

Include files 




struct rem_get_uid 

{ 

PROCESS pid; 

}; 

struct remr_get_uid 

{ 

OSUSER uid; 

}; 


rem_get_signal

em_hunt 

Include files 



struct rem_hunt 

{ 

OSUSER user; 

PROCESS from; 

OSBOOLEAN persistent; 

/* Set if a hunt 

* signal is 

* present. 

*/ 

char name[1]; /* Variablesize */ 

}; 


struct remr_hunt 

{ 

PROCESS pid; 

OSBOOLEAN found; 


rem_intercept 

Include files 

}; 

/* 0=no, 

* 1=found, 

* 2=found 

* unnamed 

*/ 



struct rem_intercept 

{ 

PROCESS pid; 

}; 


None. 

rem_resume 

Include files 



struct rem_resume 

{ 

PROCESS pid; 

}; 


None. 


rem_hunt

em_set_bp 

Include files 




struct rem_set_bp 

{ 

PROCESS pid; 

OSADDRESS address; 

OSADDRESS attribute; 

OSBUFSIZE sigsize; 

unsigned char trapsig_contents[1]; 

/* Variablesize */ 

}; 

struct remr_set_bp 

{ 


}; 

rem_set_env 


Include files 




struct rem_set_env 

{ 

PROCESS pid; 

OSBUFSIZE name; 

/* Index into strings.*/ 

OSBUFSIZE value; 

/* Index into strings.*/ 

char strings[1]; 

/* Variable size */ 

}; 

struct remr_set_env 

{ 


}; 

rem_set_fsem 

Include files 




struct rem_set_fsem 

{ 

PROCESS pid; 

OSFSEMVAL value; 

}; 

None. 


rem_set_bp

em_set_mem 

Include files 




struct rem_set_mem 

{ 

PROCESS pid; 

void *from; 

OSADDRESS to; 

OSADDRESS size; 

}; 

struct remr_set_mem 

{ 


}; 

rem_set_pcb 


Include files 



rem_signal_fsem 


struct rem_set_pcb 

{ 

PROCESS pid; 

char cpuregs[1]; /* Variable size */ 

}; 

struct remr_set_pcb 

{ 


}; 

Include files 




struct rem_signal_fsem 

{ 

PROCESS pid; 

}; 

None. 


rem_set_mem

em_start 

Include files 




struct rem_start 

{ 

PROCESS pid; 

}; 

None. 

rem_stop 

Include files 




struct rem_stop 

{ 

PROCESS pid; 

}; 

None. 



rem_start

5.3 Example of a Link Handler 

The following is a simple example of how to use the remote calls when writing a link handler. This 

link handler manages only remote hunt signals; other remote call types are handled in a similar 

manner. 




{ 

/* Defines the signals in the ose_rem.h file that 

* are being used. 

*/ 

union SIGNAL 

{ 

struct remote_call remote_call; 

struct remote_response remote_response; 

remote_cancel remote_cancel; 

}; 

union SIGNAL *signal; 

static const SIGSELECT any_sig[]={0}; 

struct OS_redir_table redir_table[1]; 

PROCESS phantom_; 

/* Redirects all signals to the current process. */ 


redir_table[0].sig = (SIGSELECT) 1; 

redir_table[0].pid = current_process(); 

for(;;) 

{ 

signal = receive((SIGSELECT *)any_sig); 

if (signal->sig_no == REMOTE_CALL) 

{ 

switch(signal->remote_call.call_type) 

{ 

case REM_HUNT: 

/* Create a phantom process with the name 

* stated in the hunt call. 

*/ 

phantom_ = create_process(OS_PHANTOM, 

signal->remote_call.params. 

rem_hunt.name, 

(OSENTRYPOINT *) 0, 

(OSADDRESS) 0, 

(OSPRIORITY) 0, 

(OSTIME) 0, 

(PROCESS) 0, 

&redir_table, 

(OSVECTOR) 0, 

(OSUSER) 0); 

/* Define the response signal 

* and its parameters 

*/ 

signal->sig_no = REMOTE_RESPONSE; 

signal->remote_response.results.remr_hunt.found= 1; 

signal->remote_response.results.remr_hunt.pid = phantom_; 

break; 


rem_stop

} 

} 

default: 

/* No hunt signal received, cannot manage 

* the request. 

*/ 

signal->sig_no = REMOTE_CANCEL; 

} 

send (&signal, sender(&signal)); 

/* Send the signal*/ 

/* to the caller. */ 

} 


{ 

/* The signal received is a signal sent to a process 

* in another CPU. Code is needed here to send the signal 

* over the communication link to a link handler in the 

* other CPU. 

*/ 

} 



rem_stop

6 Error Messages 


6.1 Kernel Error Message Reference 

The following is a list of all constants, in hexadecimal representation, used by the kernel to indicate 

which error caused a call to the error handler. 

Error Code Symbolic name 

0x01 

OSE_ESTACK_TOO_LARGE 

Too large stack buffer requested. There is no stack of this size or larger in the pool 

attached to process that called create_process. The extra parameter contains the 

size requested. 

0x02 

OSE_ENO_USER_STACKSPACE 

Out of space in a user stack pool. An error handler may extend the pool with the 

extend_pool() system call. The extra parameter contains a pool identifier that can 

be passed to the extend_pool() system call. The extra parameter serves no other 

purpose. This error code can be ignored only if the pool was extended. Ignoring 

the error causes the current allocation to be retried. 

Note that the error handler is called in a state where the dispatcher is locked. The 

error handler is therefore not allowed to perform any operations or system calls 

that would cause a process switch to be attempted. As a special case, it is however 

possible to use the kill_proc(), signal_fsem() and signal_sem() calls because these 

calls were designed to work in this situation. 

Further, if the pool serves interrupt or timer processes, the error handler is 

assumed to disable interrupts before calling extend_pool() and restoring the 

previous interrupt status upon return. 

0x03 

OSE_ETOO_MANY_PROCESSES 

Too many processes were created. The system tables allows only a certain number 

of processes. This number was exceeded. As the process table is used to store any 

object that is represented by a PROCESS id, this error may also be reported when 

creating new blocks, pools or segments. 

Ignoring this error causes the system call to return as if it was never called. 

0x11 

OSE_EBUFFER_TOO_LARGE 

Too large signal buffer requested.It is impossible to allocate a buffer larger than 

the largest size available in the pool.The extra parameter contains the size 

requested. Ignoring this error causes the kernel to allocate the largest buffer 

available in the pool.This error is fatal if it occurs when the kernel tries to allocate 

system pool space as a side effect of system calls like create_block(), 

create_process() etc. 

0x12 

OSE_ENO_KERN_SPACE 

Out of space in the kernel pool. An error handler may extend the pool with the 



Error Messages


0x1d 

0x1e 

0x1f 

0x20 

0x21 



the error causes the current allocation to be retried. Note that the error handler is 

called in a state where the dispatcher is locked. The error handler is therefore not 

allowed to perform any operations or system calls that would cause a process 

switch to be attempted. As a special case, it is however possible to use the 

signal_fsem() and signal_sem() calls because these calls were designed to work 

in this situation. Further, if the pool serves interrupt or timer processes, the error 

handler is assumed to disable interrupts before calling extend_pool() and restoring 

the previous interrupt status upon return. 

OSE_EKILLED_STATIC_SEMAPHORE 

An attempt to kill a static semaphore was made.Only semaphores created with the 

create_sem system call can be killed. 

OSE_EKILLED_SEMAPHORE_IN_USE 

An attempt to kill a semaphore that is still in use was made. A semaphore can not 

be killed when there are processes waiting at it. 

OSE_EILLEGAL_SEMAPHORE 

An illegal semaphore pointer was presented to the kernel. This error also occurs 

when a semaphore that is not available to the calling process is killed. A 

semaphore in another memory segment is unavailable in some memory 

configurations. Ignoring this error causes the system call to return as if it was 

never called. 

OSE_ENO_USER_SIGSPACE 

Out of space in a user signal pool. An error handler may extend the pool with the 




the error causes the current allocation to be retried. 

Note that the error handler is called in a state where the dispatcher is locked. The 

error handler is therefore not allowed to perform any operations or system calls 

that would cause a process switch to be attempted. As a special case, it is however 

possible to use the kill_proc(), signal_fsem() and signal_sem() calls because these 

calls were designed to work in this situation. 

Further, if the pool serves interrupt or timer processes, the error handler is 

assumed to disable interrupts before calling extend_pool() and restoring the 

previous interrupt status upon return. 

OSE_EPOOL_EXTENSION_FAILED 

Pool extension failed. An error handler repeatedly claims that an out of space 

error was handled, but the kernel can not find the extended space. It is possible 

that the error handler never used the extend_pool() system call. 

The extra parameter contains a the initial error code. I.e one of: 


Error Messages


0x22 

0x23 

0x24 

0x25 

0x26 

0x27 

0x28 

• OSE_ENO_KERN_SPACE 

• OSE_ENO_USER_SIGSPACE 

• OSE_ENO_USER_STACKSPACE. 

This error is fatal when it occurs in an interrupt process. If it is not, the error 

handler is expected to kill the current process. For errors in the kernel pool, the 

recover procedure may not be straight forward so it is recommended that the 

system is shut down or restarted by the system error handler. 

OSE_EBLOCK_HAS_PROCESSES 

The create_pool system call was used on a block that contains processes. 

OSE_EUNREASONABLE_SIZES 

The create_pool system call was exposed to an illegal signal size table or stack 

size table. This error code is used in any of the following illegal cases: 

1. The count field in the first location is unreasonable. 

Valid counts are 0-8, but both tables can not have a count of zero. 

2. The supplied memory fragment does not fit in the address space. 

3. The size table is not properly sorted on size. 

4. All sizes in a table are zero. 

Ignoring this error causes the system call to return as if it was never called. 

OSE_ETOO_MANY_ATTACHED 

Too many signals were attached. The system tables allows only a certain number 

of attached signals. This number was exceeded. 

OSE_EVECTOR_IN_USE 

Vector already in use. An interrupt process was created for a vector that is already 

allocated to another interrupt process. The extra parameter contains the vector. 

Ignoring this error causes the interrupt process to be removed from the system as 

if it was never created. 

OSE_EILLEGAL_SYSTEMCALL 

Illegal system call from an interrupt process. The current interrupt or timer 

process has been using a system call that is only allowed for non interrupt 

processes. 

OSE_EINTERSEGMENT_SEND 

Illegal intersegment send to an interrupt or timer process. Signals can be sent to 

interrupt or timer processes only if the pool associated with the target process is 

in the same memory segment as the pool associated with the sending process. 

This restriction is present because an interrupt process can not handle the page 

fault that might occur when a reference to the senders memory segment is made 

at the time of the receive call in the interrupt process. 

OSE_EBAD_INTLEVEL 

Illegal wakeup priority for an interrupt process. The current interrupt process was 

invoked with a hardware priority that does not match the priority stated when the 


Error Messages


0x29 

0x2a 

0x2b 

0x2c 

0x2d 

0x2e 

interrupt process was created. The priority parameter in the create_process call 

must match the actual hardware priority at which the interrupt occurs. 

The extra parameter to the error handler contains the actual priority 

encountered.Ignoring this error causes the process priority to be updated. 

OSE_ERECURSIVE_ERROR 

An error was encountered while an error handler was executing. The situation was 

detected in an error system call made by the current process. The extra parameter 

to the error handler contains the error code supplied in the error system call. This 

error must be handled in a system error handler by killing the current process/ 

program. The error can not be ignored, and attempting to ignore it will only cause 

the error to be reported again with the fatal flag set. 

OSE_ERECURSIVE_SYSERROR 

An error was encountered while an error handler was executing.The situation was 

detected when an error detected by OSE was about to be reported. The extra 

parameter to the error handler contains the error code that was about to be 

reported by OSE when the recursive error call was detected. This error must be 

handled in a system error handler by killing the current process/program. The 

error can not be ignored, and attempting to ignore it will only cause the error to 

be reported again with the fatal flag set. 

OSE_EILLEGAL_SEM_VALUE 

An semaphore with a negative initial value was found or created. This is an illegal 

situation since a negative semaphore value implies that one or more processes are 

waiting at the semaphore. The extra parameter contains the illegal initial value. 

Ignoring this error causes the semaphore to be created with an initial value set to 

zero. 

OSE_EINTERSEGMENT_SEMAPHORE_REF 

A semaphore in use was implicitly killed, but processes are still waiting at it. This 

error occurs when processes erroneously use a semaphore located in another 

memory segment. This is illegal, but in a system without memory protection it 

works up to the point when the memory segment containing the semaphore is 

reclaimed. This occurs when all processes in that segment have been killed. This 

error must be handled in a system error handler by killing the offending process. 

The id of this process is passed to the error handler in the extra parameter. 

OSE_EDETACHED_TWICE 

An attempt to detach from an already detached process was made.Only one detach 

call may be issued for each attach call made.This error may also occur if detach 

is called with a bad parameter.The kernel can not understand the difference in all 

cases. Ignoring this error causes detach() to perform no operation. 

OSE_EDETACHED_TOO_LATE 

An attempt was made to detach from a process long after the death of that 

process.This error implies that the attached process has been killed, and the caller 


Error Messages


0x2f 

0x30 

0x31 

0x32 

0x47 

0x48 

0x49 

0x4a 

failed to notice this for a period long enough for the kernel to discard all attach 

information for that process. The error can sometimes occur as a result of a too 

small number of attach entries defined in the kernel configuration. If you 

encounter this error for no apparent reason, then try increasing the attach limit in 

the configuration file. This error may also occur if detach is called with a bad 

parameter. The kernel can not understand the difference in all cases. Ignoring this 

error causes the same effect as if detach() was never called, i.e the caller must be 

prepared to receive a subsequent attached signal from the killed process. 

OSE_EDETACH_AFTER_RECEIVE 

An attempt was made to detach from a process when the attached signal has 

already been received. 

OSE_EBAD_PROCESS_TYPE 

An attempt was made to create a process of an invalid type. 

OSE_EUSED_NIL_POINTER 

The caller tried to operate on the NIL pointer. The buffer has probably been sent 

or freed already. The extra parameter contains the address of the signal pointer 

that points to NIL. Ignoring this error causes the illegal system call to be ignored. 

OSE_EILLEGAL_PROCESS_ID 

An illegal block or process id was presented to the kernel.This code may also 

indicate a bad process id in a redirection table.The extra parameter contains the 

offending id.Ignoring this error causes the system call to treat the id as the id of 

a killed process. 

OSE_EILLEGAL_FLUSH_SENDER 

An invalid process id was encountered in the flush system call.The invalid id was 

found in the array specifying from which processes signals should be 

discarded.This error may also indicate that the first entry of the array contains an 

invalid array size. 

OSE_EKILLED_STATIC_PROCESS 

A static process was killed. Killing a static process is illegal in a system linked 

to an OSE realtime kernel.The error was reported by the system daemon, which 

detected the death of the main process in osemain.c. It is unknown at this time 

which process was originally killed, since all static processes are now dead. 

OSE_EILLEGAL_REDIRCOUNT 

An invalid redirection table was presented to the kernel. The count of number of 

entries was zero. It must always be at least one, since the first table entry 

containing the count and the default process id is included in the counter. Ignoring 

this error causes the illegal system call to be ignored. 

OSE_ECORRUPTED_KERNEL 

Kernel data was damaged. The kernel tables were found to be inconsistent.Kernel 

data may have been damaged by a crashed process.The extra parameter contains 

an undocumented subcode. 


Error Messages


0x52 

0x53 

0x54 

0x55 

0x56 

0x57 

0x58 

OSE_ESPURIOUS_INTERRUPT 

An interrupt occurred from an unused interrupt vector. There may be several 

reasons for this. Possible reasons might be that hardware capable of generating 

interrupt was erroneously initialized, or the system was restarted without issuing 

a proper hardware reset, or an interrupt process might have been killed without 

disabling the corresponding hardware.The extra parameter to the error handler 

contains the priority on which the interrupt was encountered. 

OSE_EATTACHED_TO_CALLER 

An attempt was made to attach to the current process. 

It is illegal to issue an attach call with the id of the calling process as a parameter. 

OSE_EINTERSEGMENT_COPY_FAILED 

The current receive(from/w_tmo) system call failed because the pool attached to 

the calling process does not support the size of the signal received. Planning pools 

with regard to the largest available buffer size is an important issue in systems 

where intersegment memory protection is utilized. It is nearly always advisable to 

have all pools support a largest signal size of 64k bytes. The extra parameter to 

the error handler contains the size of the signal buffer found in the receive queue. 

Ignoring this error causes the received signal to be lost. 

OSE_EINTSTACK_TOO_LARGE 

Too large interrupt stack buffer requested.There is no interrupt stack of sufficient 

size in the system pool.The extra parameter contains the accummulated size. This 

error does not necessarily mean that a real problem is present since the interrupt 

stack size accumulates worst stack case requirements on each interrupt priority 

over the system life. 

If the system is designed such that interrupt processes are frequently created and 

killed on various interrupt priorities, then a situation may arise where the kernel 

thinks that the interrupt stack needs to be larger than actually required by interrupt 

processes currently in operation. Ignoring this error causes the interrupt stack to 

be silently truncated to the largest size available. 

OSE_EKILLED_SYSTEM_DAEMON 

An attempt was made to kill a system daemon. Killing a member of the OSE 

block such as “ose_sysd” or “idle” is not allowed.The extra parameter to the error 

handler contains the process id of the system daemon. Ignoring this error causes 

the kill_proc call to return without killing the system daemon. 

OSE_ECANNOT_RESTORE 

Restore was attempted on a signal buffer that has already been freed or is 

otherwise not owned by any process. Such buffers can not be restored. This error 

may also occur for a wild signal pointer. The extra parameter contains the address 

of the signal buffer. 

OSE_EFRAGMENT_TOO_SMALL 


Error Messages


0x59 

0x5a 

0x5b 

0x5c 

0x5d 

0x5e 

An attempt was made to install an unreasonably small pool or pool fragment. 

Pool fragments smaller than 1024 bytes are rendered useless. This is an arbitrary 

limit, selected because it is believed that fragments this small are always useless. 

As a general guideline, fragments should be at least several times the size of the 

largest buffer or stack size. The extra parameter to the error handler contains the 

size of the supplied pool fragment. Ignoring this error causes the system call to 

return without creating the pool or installing the pool extension. I.e. as if the call 

was never made. 

OSE_ECONCURRENT_TICK_CALL 

Tick was called concurrently by several processes. Tick is a non reentrant system 

call. Only one process at a time may use it, or the system will crash. This is a 

fatal error. 

OSE_EILLEGAL_USER_CALL 

A superuser system call was used by a non superuser process. Some system calls 

are reserved for use by processes with a user number of zero (the superuser 

number). Using these calls in other processes is illegal. Ignoring this error causes 

the illegal system call to be ignored. 

OSE_EALLREADY_STARTED 

An attempt was made to start a process that is not stopped. The start() system 

call was invoked with either a process or a block id. For a block id, the block was 

found to contain at least one process that was not stopped. The extra parameter 

contains the id that was passed to the start() call. Ignoring the error causes the 

start() system call to continue, starting only stopped processes. 

OSE_ELINKHANDLER_DEADLOCK 

A linkhandler deadlock was detected. This error was probably caused by a 

linkhandler process issuing a hunt() system call or another system call that can 

cause a remote system call request. Doing this is a design rule violation. It is 

however possible that the error was instead caused during debugging or if the 

linkhandler was stopped or intercepted for more than 10 seconds. The extra 

parameter contains the process id of the linkhandler that did not respond. 

Ignoring this error causes the kernel to continue waiting for a response. 

OSE_EILLEGAL_ENVNAME 

An illegal environment variable name was detected. A set_env() or get_env() call 

was issued with a name parameter set to NULL. This was probably caused by a 

problem related to uninitialized variables. Ignoring this error causes the illegal 

system call to be ignored. 

OSE_EILLEGAL_POOL 

An illegal pool id was presented to the kernel. The extend_pool() call was issued 

with a pool_id parameter that refers to an object that is not a pool. This was 

probably caused by a problem related to uninitialized variables. Ignoring this 

error causes the illegal system call to be ignored. 


Error Messages


0x5f 

0x70 

0x71 

0x72 

0x73 

0x74 

0x75 

OSE_ENOT_SIG_OWNER 

The calling process is not the owner of the specified signal buffer. This error may 

sometimes also occur for a wild signal pointer. The extra parameter contains the 

address of the signal buffer. Ignoring this error causes the illegal system call to 

be ignored. 

OSE_EWILD_SIG_POINTER 

An invalid signal pointer was presented to the kernel. The operating system was 

unable to identify the memory pointed to as a signal buffer. The extra parameter 

contains the offending pointer, that is the address that should have contained a 

signal number. Ignoring this error causes the illegal system call to be ignored. 

OSE_EBAD_PARAMETER 

An invalid parameter was used in a system call. The operating system checks 

many of the system call parameters for unreasonable values. This error code 

means that one of the parameters to the indicated system call contained an illegal 

value. The extra parameter contains the value of the offending parameter. 

Ignoring this error causes the illegal system call to be ignored. 

OSE_EFRAGMENT_IN_USE 

An attempt was made to create a pool with a memory area that is already used in 

another pool. This error commonly occurs when a block is killed and recreated. 

The old pool is probably still in use because it contains signals that are currently 

owned by a process that is still alive. Pools don’t die until the last signal in the 

pool has been freed. This error can also be reported if pool space is by mistake 

allocated on the stack of the caller. The extra parameter contains the base of the 

offending pool space. Ignoring this error causes the illegal system call to be 

ignored. 

OSE_EILLEGAL_SUPER_MODE 

An illegal attempt was made to create a supervisor mode block. Supervisor mode 

blocks can only be created by a superuser process executing in supervisor mode. 

The extra parameter contains a pointer to the name of the new block. Ignoring 

this error causes the block to be created anyway, but the mode is set to user mode. 

OSE_ESPURIOUS_SYSTEM_SIGNAL 

An unrecognized signal was received by one of the system daemon processes. 

The extra parameter contains the process id of the sender of the unknown signal. 

Ignoring this error causes the signal to be silently freed. 

OSE_EFRAGMENT_TOO_LARGE 

An attempt was made to install an unreasonably large pool or pool fragment. The 

size of the pool fragment presented to the kernel is too large for the fragment to 

fit in the address space. This error indicates either that the size is unreasonably 

large, or that the base of the memory fragment is too close to the end of the 

address space. The extra parameter to the error handler contains the size of the 

supplied pool fragment. Ignoring this error causes the system call to return 


Error Messages


0x76 

0x77 

0x78 

0x79 

0x7a 

0xa5 

0xa6 

without creating the pool or installing the pool extension. I.e. as if the call was 

never made. 

OSE_ESTOP_OVERFLOW 

An attempt was made to stop a process an unreasonable number of times. This 

error occurs when the stop-counter wrapps from 4 Giga times to zero. The extra 

parameter to the error handler contains the id of the process stopped. Ignoring 

this error causes the system call to return without executing the stop operation. 

I.e. as if the call was never made. 

OSE_ESEM_OVERFLOW 

An attempt was made to signal a semaphore or a fast semaphore beyond the 

maximum value. Semaphores can only be signaled a limitied number of times 

before a wait operation is performed. This error occurs when the semaphore value 

wrapps from 2 Giga times to -2 Giga times. The extra parameter to the error 

handler contains the address of the semaphore or the process id to which the fast 

semaphore belongs. Ignoring this error causes the system call to return without 

executing the semaphore operation. I.e. as if the call was never made. 

OSE_EBAD_HUNT_PRI 

This is the result of a bad kernel configuration. The huntd priority is too low. The 

ose_huntd process must have a priority higher than the ose_sysd process. Ignoring 

this error causes the priorities to be automatically adjusted. 

OSE_EILLEGAL_PRISYSTEMCALL 

An illegal system call was made from interrupt or background process. The 

current background, interrupt or timer process has been using a system call that 

is only allowed for prioritized processes. 

OSE_EILLEGAL_CONFIGURATION 

This is the result of an illegal kernel configuration. One or more entries in the 

kernel configuration file has an illegal value. The extra parameter to the error 

handler contains this value. Ignoring this error will cause the kernel to adjust the 

value to the closest legal value. 

OSE_ENO_BUFFER_END_MARK 

A valid end mark could not be found in the signal buffer presented to the kernel. 

The calling process seems to have been writing more data than the size of the 

buffer allows. The extra parameter contains the address of the signal buffer. This 

error must be handled in a system error handler by killing the current process/ 

program. The error can not be ignored, and attempting to ignore it will only cause 

the error to be reported again with the fatal flag set. 

OSE_ECORRUPTED_POOL 

A damaged signal buffer was presented to the kernel. Analysis indicates that the 

problem was caused by some other buffer in which a process has been writing 

more data than the size of the buffer allows. 


Error Messages

The extra parameter contains a pointer to a structure with four 32 bit entries and 

the following layout: 

• extra[0] 

The process id of the other process that may have caused the problem. The field 

may contain the id of any process including the current. The field is zero if the 

id could not be obtained. 

• extra[1] 

A pointer to the name of the other process. The field is zero if the name could 

not be obtained. 

• extra[2] 

A pointer to the signal buffer that was damaged by the indicated process. This 

is probably the buffer which was originally damaged. 

• extra[3] 

A pointer to the damaged signal buffer that was presented to the kernel by the 

calling process. This is probably only a secondary error indication caused by 

the extra[2] buffer. 


6.1.1 Target-specific error codes 

These error codes are only valid for realtime kernels not softkernels. 

0x101 

OSE_EUSER_STACK_OVERFLOW 

Stack overwrite in user stack. The extra parameter contains address of stack end. 

0x102 

OSE_ESUPERV_STACK_OVERFLOW 

Stack overwrite in supervisor stack. The extra parameter contains address of stack 

end. 

0x103 

OSE_EINTERRUPT_STACK_OVERFLOW 

Stack overwrite in interrupt stack. The extra parameter contains address of stack 

end. 

0x104 

OSE_EUNKNOWN_BREAKPOINT 

An unknown breakpoint was encountered. 

0x105 

OSE_EUNKNOWN_INTERRUPT 

An unknown interrupt was encountered. The extra parameter contains vector 

number. 

0x107 

OSE_EPROCESS_ENDED 

A prioritised or background process ended. This error should be treated as a 

warning. The extra parameter contains the process id. 

0x108 

OSE_ESTART_STACK_OVERFLOW 

Stack overwrite in kernel startup stack. A handler has used too much stack space. 

The extra parameter contains address of stack end. 

0x110 

OSE_EUNDEFINED_SYSCALL_CODE 


Error Messages

0x111 

0x112 

An undefined function code has been used for a system call. The extra parameter 

the contains function code. 

OSE_EUNEXPECTED_EXCEPTION 

An unexpected exception occured. The exception offset is supplied in the subcode 

field. The extra parameter contains the pc register (the Program counter). 

OSE_EPRIORITY_ERROR 

An interrupt has occurred with equal or less priority than the currently running 

interrupt process. The reason for this is probably that interrupts have not been 

masked properly in the interrupt controller. The interrupt controller must not allow 

an interrupt process to be interrupted by an interrupt process with equal or lower 

priority. The extra parameter contains the illegal priority. This error is only valid 

on PowerPC targets. 



Error Messages


6.2 Caller Information Reference 

The following is a list of all constants used to determine which system call was in progress when 

an error was encountered. 

Caller No 

Symbolic routine name 

0x010000 

OSE_ADDRESSEE 

0x020000 

OSE_ALLOC 

0x030000 

OSE_ASSIGN_LINKHANDLER 

0x040000 

OSE_ATTACH 

0x050000 

OSE_ATTACH_SEGMENT 

0x060000 

OSE_CLEAR_BP 

0x070000 

OSE_CREATE_BLOCK 

0x080000 

OSE_CREATE_ERROR_HANDLER 

0x090000 

OSE_CREATE_POOL 

0x0a0000 

OSE_CREATE_PROCESS 

0x0b0000 

OSE_CREATE_SEM 

0x0c0000 

OSE_CURRENT_PROCESS 

0x0d0000 

OSE_DELAY 

0x0e0000 

OSE_DETACH 

0x0f0000 

OSE_ERROR 

0x100000 

OSE_FLUSH 

0x110000 

OSE_FREE_BUF 

0x120000 

OSE_GET_BID 

0x130000 

OSE_GET_BID_LIST 

0x140000 

OSE_GET_CPU 

0x150000 

OSE_GET_ENV 

0x160000 

OSE_GET_ENV_LIST 

0x170000 

OSE_GET_FSEM 

0x180000 

OSE_GET_MEM 

0x190000 

OSE_GET_PCB 

0x1a0000 

OSE_GET_PID_LIST 

0x1b0000 

OSE_GET_PRI 

0x1c0000 

OSE_GET_PTYPE 

0x1d0000 

OSE_GET_SEM 

0x1e0000 

OSE_GET_SIGNAL 

0x1f0000 

OSE_GET_SYSTIME 

0x200000 

OSE_GET_TICKS 


Error Messages


Caller No 

0x210000 

0x220000 

0x230000 

0x240000 

0x250000 

0x260000 

0x270000 

0x280000 

0x290000 

0x2a0000 

0x2b0000 

0x2c0000 

0x2d0000 

0x2e0000 

0x2f0000 

0x300000 

0x310000 

0x320000 

0x330000 

0x340000 

0x350000 

0x360000 

0x370000 

0x380000 

0x390000 

0x3a0000 

0x3b0000 

0x3c0000 

0x3d0000 

0x3e0000 

0x3f0000 

0x400000 

0x410000 

0x420000 

0x440000 

Symbolic routine name 

OSE_GET_UID 

OSE_HUNT 

OSE_HUNT_FROM 

OSE_INTERCEPT 

OSE_KILL_PROC 

OSE_KILL_SEM 

OSE_POWER_FAIL 

OSE_RECEIVE 

OSE_RECEIVE_FROM 

OSE_RECEIVE_W_TMO 

OSE_RESTORE 

OSE_RESUME 

OSE_SEND 

OSE_SENDER 

OSE_SEND_W_S 

OSE_SET_BP 

OSE_SET_ENV 

OSE_SET_FSEM 

OSE_SET_MEM 

OSE_SET_PCB 

OSE_SET_PRI 

OSE_SET_SEGMENT 

OSE_SIGSIZE 

OSE_SIGNAL_FSEM 

OSE_SIGNAL_SEM 

OSE_START 

OSE_START_OSE 

OSE_STOP 

OSE_SYSTEM_TICK 

OSE_TICK 

OSE_WAIT_FSEM 

OSE_WAIT_SEM 

OSE_WAKE_UP 

OSE_EXTEND_POOL 

OSE_SET_PRI_FOR 


Error Messages

6.3 Interface Library Errors 

This is a summary of error codes, in hexadecimal representation, used by the interface library, which 

is described in the OSE Real Time Kernel User’s Guide. 

Error Code 

Description 

0x9520 

0x9521 

0x9522 

0x9523 

The system can not be created due to a circular dependency 

between blocks, remote call server processes, redirection tables and 

processes. 

An external process could not be found within the specified 

timeout. 

No static processes were found. There must be at least one. 

An unexpected value appear in a statically initialized test variable. 

This is a check that initialization of static C variables works. 



Error Messages


6.4 Kernel Error Summary 

This is a summary of the error code list in the previous chapter. 

Error Code Description 

0x01 

Too large stack buffer requested. 

0x02 

Out of space in user stack pool. 

0x03 

Too many processes were created. 

0x11 

Too large signal buffer requested. 

0x12 

Out of space in kernel pool. 

0x1d 

An attempt to kill a static semaphore was made. 

0x1e 

An attempt to kill a semaphore that is still in use was made. 

0x1f 

An illegal semaphore pointer was presented to the kernel. 

0x20 

Out of space in user signal pool. 

0x21 

Pool extension failed. 

0x22 

The create_pool system call was used on a block that contains processes. 

0x23 

The create_pool system call was presented a signal size table or a stack size table 

that contains an unreasonable number in the first location. 

0x24 

Too many signals were attached. 

0x25 

Vector already in use. 

0x26 

Illegal system call from an interrupt process. 

0x27 

Illegal intersegment send to an interrupt or timer-interrupt process. 

0x28 

Illegal wakeup priority for an interrupt process. 

0x29 

An error was encountered while an error handler was executing. 

0x2a 

An error was encountered while an error handler was executing. 

0x2b 

A semaphore with a negative initial value was found or created. 

0x2c 

A semaphore in use was implicitly killed, but processes are still waiting at it. 

0x2d 

An attempt to detach from an already detached process was made. 

0x2e 

An attempt was made to detach from a process long after the death of that 

process. 

0x2f 

An attempt was made to detach from a process when the attached signal has 

already been received. 

0x30 

An attempt was made to create a process of an invalid type. 

0x31 

The caller tried to operate on the NIL pointer. 

0x32 

An illegal block or process ID was presented to the kernel. 

0x47 

An invalid process ID was encountered in the flush system call. 

0x48 

A static process was killed. Killing a static process is illegal. 

0x49 

An invallid redirection table was presented to the kernel. 

0x4a 

Kernel data was damaged. 


Error Messages


0x52 

0x53 

0x54 

0x55 

0x56 

0x57 

0x58 

0x59 

0x5b 

0x5c 

0x5d 

0x5e 

0x5f 

0x70 

0x71 

0x72 

0x73 

0x74 

0x75 

0x76 

0x77 

0x78 

0x79 

0x7a 

0xa5 

0xa6 

An interrupt occured from an unused interrupt vector. 

An attempt was made to attach to the current process, this is illegal. 

The current receive (or similar) system call failed because the pool attached to the 

current process does not support the size of the signal received. 

A too large interrupt stack was requested. 

An attempt was made to kill a system daemon, this is illegal. 

Restore was attempted on a signal buffer that has already been freed or is 

otherwise not owned by any process. 

An attempt was made to install an unreasonably small pool fragment. 

The tick system call was called concurrently by several processes. 

An attempt was made to start a process that is not stopped. 

A linkhandler deadlock was detected. 

An illegal environment variable name was detected. 

An illegal pool id was presented to the kernel. 

The calling process is not the owner of the specified signal buffer. 

An invalid signal pointer was presented to the kernel. 

An invalid parameter was used in a system call. 

An attempt was made to create a pool with a memory area that is already used in 

another pool. 

An illegal attempt was made to create a supervisor mode block. 

An unrecognized signal was received by one of the system daemon processes. 

An attempt was made to install an unreasonably large pool or pool fragment. 

An attempt was made to stop a process an unreasonable number of times. 

An attempt was made to signal a semaphore or a fast semaphore beyond the 

maximum value. 

The huntd priority is too low. The ose_huntd process must have a priority higher 

than the ose_sysd process. 

An illegal system call was made from interrupt or background process. 

One or more entries in the kernel configuration file has an illegal value. 

A valid end mark could not be found in the signal buffer presented to the kernel. 

A damaged signal buffer was presented to the kernel. 


Error Messages

6.4.1 Target-specific error summary 

0x101 

A user stack overflow was encountered. 

0x102 

A supervisor stack overflow was encountered. 

0x103 

An interrupt stack overflow was encountered. 

0x104 

An unknown breakpoint was encountered. 

0x105 

An unknown interrupt was encountered. 

0x107 

A prioritized or background process ended. 

0x108 

Startup stack overflow. 

0x110 

An undefined function code has been used for a system call. 

0x111 

An unexpected exception occurred. 

0x112 

An interrupt has occurred with equal or less priority than the currently running 

interrupt process. 



Error Messages

7 Glossary 


ANSI 

ASCII 

attach 

block 

buffer 

configuration 

debugging 

default 

dispatch 

dispatcher 

dynamic process 

environment variable 

error checks 

event 

fast semaphore 

fault tolerant system 

American National Standards Institute. 

American National Standard Code for Information Interchange. 

In OSE, a system call that attaches a signal to a process. Attached 

signals are returned to their owners when the process with the 

attached signals is killed. 

OSE processes can be grouped together into blocks. Several 

commands allow blocks to be operated upon as single units. The 

block is an excellent means of grouping logically connected 

processes into bigger and fewer functional units. 

A section of memory. It is reserved using the alloc system call. A 

buffer always has an owner. 

The operating system may contain different parts of code and 

parameters and behave differently depending on the configuration. 

Locating and removing errors from a system. 

An attribute, value or option that is used when no alternative is 

specified. 

To swap out a running process and swap in another ready process. 

A part of the kernel which performs a dispatch. 

A process that can be created and killed during run-time. 

Using OSE environment variables it is possible for a process to 

distribute information to other processes. Environment variables 

should be used sparingly and only for infrequently updated 

information. 

An ability to turn on or turn off certain error checking in OSE. This 

capability allows the OSE user to get maximum speed when error 

checking is no longer needed. 

1. Something which happens in the system. For example, the 

operator may have pressed a button or a resource becomes 

available. Events are often connected to interrupts or polled. 

2. For the DDS, event has a special meaning; an event is when a 

user defined condition is fulfilled. 

The fastest way in OSE to obtain process synchronisation. A fast 

semaphore does not give the possibility to transfer information 

between processes. A process cannot have more than one fast 

semaphore. 

A single or multi CPU system capable of recovering from different 

kinds of errors or malfunctions. 


Glossary


handlers 

hunt 

intercepted 

interface 

interrupt 

interrupt process 

kernel 

level A 

level B 

level C 

level D 

link handler 

logical channel 

MMU 

multi CPU systems 

NIL 

NULL 

phantom process 

pool 

In OSE, a handler is a piece of code which is automatically 

executed when a system event has occurred. Examples of handlers 

are swap in handler, swap out handler and send handler. 

Availability of handlers is strongly implementation dependent. 

An OSE system mechanism, mainly used for multi-CPU 

communication, to get the process identity of a named process. 

A state an OSE process enters when a breakpoint is reached. 

The boundary between processes. Together, all possible contacts 

between two processes defines their interface. In OSE, the process 

interface consists of the signals exchanged between the processes. 

An event which, through hardware or software, causes the CPU to 

transfer control from the currently running process to an interrupt 

process. 

An OSE interrupt process is called when a hardware or software 

interrupt occurs. Two types of interrupt processes exist in OSE; 

interrupt processes and timer-interrupt processes. 

The central part of an operating system which handles things like 

dispatching, resource allocation and inter process communication. 

The simplest of the OSE implementation levels. Also known as the 

portable set. 

The OSE implementation levels which contains all necessary parts 

to build a distributed real time system. 

Complete kernel configuration except for memory management, 

local pools, user numbers and complete breakpoint functionality. 

The complete kernel configuration. 

Handles signal exchange between remote processes in an OSE 

system. 

A link between remote processes that is managed by a link handler. 

A memory management unit (MMU) is hardware capable of 

protecting memory areas from illegal access. 

A system with more than one CPU and with some connection 

between the CPUs. 

A constant defined by OSE. Used as a return value in receive, 

receive_w_tmo and receive_from system calls when no signal 

buffer could be received. 

A pointer guaranteed not to point to a data object. 

An empty process with an optional redirection table. 

A contiguous area of memory from which signal buffers, stacks 

and kernel areas are allocated. There may be more than one pool 

in OSE. 


Glossary


pre-emption 

priority 

process 

process identity 

process state 

process types 

real-time operating system 

redirection table 

re-entrant 

remote system calls 

scheduling 

segments 

semaphore 

signal 

signal redirection 

software event 

static process 

Interrupting an activity in progress immediately without letting it 

finish, and starting some other activity. 

Each process in an OSE system has a priority. The meaning of the 

priority differs between process types but always defines the order 

in which different activities will be carried out. 

Processes are the building blocks in OSE. Each process is a 

sequential program component that has its own flow-of-control, its 

own stack and CPU registers. 

In OSE a number identifying a process. It is necessary to know the 

process identity before you can send a signal to the process. 

A process running under OSE is always in one of three states; 

running, ready or waiting. 

Each OSE process is of one of the following process types; 

interrupt process, timer-interrupt process, prioritized process, 

background process or phantom process. 

Programs which have to react to external events within a limited 

time are called real-time programs. An operating system designed 

to handle such programs is a real-time operating system. 

A table defining signal routes to receivers other than the original. 

Processes may be equipped with redirection tables. 

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; 

it must use registers or stack, i.e. only relative addressing is 

allowed. The OSE system calls are re-entrant but many C-libraries 

are not. 

System calls which operate on processes or blocks in other CPUs. 

The way the operating system selects which process to run at a 

given instant. 

Pools may be grouped together into segments. 

In OSE, a way to obtain a fast process synchronisation mechanism 

when no data needs to be transferred between processes. 

The most common way in OSE to transfer information between 

processes. A signal is a buffer allocated from the kernel and usually 

contains data. 

In OSE it is possible to change the addressee of a signal. This is 

called signal redirection. Signal redirection is maintained through 

a redirection table. 

A way to wake up an interrupt process directly from another 

process by sending a signal to it. 

Processes which are created by the kernel at system start. Static 

processes may never be killed. 


Glossary

superuser 

supervisor 

swap 

system calls 

system processes 

system tick 

user number 

In OSE, a process with user number 0. The superuser has access to 

all other processes. 

A CPU dependent execution mode. In OSE a process running in 

supervisor mode does not necessarily have to be a superuser. 

Refers to exchanging control from one process to another. 

The interface between application processes and the kernel. 

Usually a function call in the C programming language. 

Internal processes in an OSE implementation. 

In OSE, system tick is a counter which is incremented by a call to 

the system function tick. Timer-interrupt processes, delays and 

timeouts are dependent on the system tick to work. The system tick 

should be generated from a system hardware timer. 

To protect functionally separated software from each other, OSE 

equips processes with user numbers. With one exception, only 

processes having the same user number may communicate with 

each other. The superuser can communicate with all processes. 



Glossary

Appendix A ASCII Character Set 

ASCII control characters 

Dec Hex Dec Hex 


0 0 NUL Null 16 10 DLE Data linkescape 

1 1 SOH Start of heading 17 11 DC1 Device control 1 

2 2 STX Start of text 18 12 DC2 Device control 2 

3 3 ETX End of text 19 13 DC3 Device control 3 

4 4 EOT End of transmission 

20 14 DC4 Device control 4 

5 5 ENQ Enquiry 21 15 NAK Negative Acknowledge 

6 6 ACK Acknowledge 22 16 SYN Synchronous 

idle 

7 7 BEL Bell 23 17 ETB End of transmission 

block 

8 8 BS Backspace 24 18 CAN Cancel 

9 9 HT Horizontal tab 25 19 EM End of medium 

10 A LF Line feed 26 1A SUB Substitute 

11 B VT Vertical tab 27 1B ESC Escape 

12 C FF Form feed 28 1C FS File separator 

13 D CR Carriage return 29 1D GS Group separator 

14 E SO Shift out 30 1E RS Record separator 

15 F SI Shift in 31 1F US Unit separator 

ASCII normal characters 

Dec Hex Dec Hex Dec Hex 

32 20 Space 64 40 @ 96 60 ’ 

33 21 ! 65 41 A 97 61 a 

34 22 " 66 42 B 98 62 b 

35 23 # 67 43 C 99 63 c 

36 24 $ 68 44 D 100 64 d 

37 25 % 69 45 E 101 65 e 

38 26 & 70 46 F 102 66 f 

39 27 ' 71 47 G 103 67 g 

40 28 ( 72 48 H 104 68 h 

41 29 ) 73 49 I 105 69 i 

Reference Manual / R1.0.4 OSE / Kernel - Appendix A : 1 

ASCII Character Set


Dec Hex Dec Hex Dec Hex 

42 2A * 74 4A J 106 6A j 

43 2B + 75 4B K 107 6B k 

44 2C , 76 4C L 108 6C l 

45 2D - 77 4D M 109 6D m 

46 2E . 78 4E N 110 6E n 

47 2F / 79 4F O 111 6F o 

48 30 0 80 50 P 112 70 p 

49 31 1 81 51 Q 113 71 q 

50 32 2 82 52 R 114 72 r 

51 33 3 83 53 S 115 73 s 

52 34 4 84 54 T 116 74 t 

53 35 5 85 55 U 117 75 u 

54 36 6 86 56 V 118 76 v 

55 37 7 87 57 W 119 77 w 

56 38 8 88 58 X 120 78 x 

57 39 9 89 59 Y 121 79 y 

58 3A : 90 5A Z 122 7A z 

59 3B ; 91 5B [ 123 7B { 

60 3C < 92 5C \ 124 7C | 

61 3D = 93 5D ] 125 7D } 

62 3E > 94 5E ^ 126 7E ~ 

63 3F ? 95 5F _ 127 7F Delete 

Reference Manual / R1.0.4 OSE / Kernel - Appendix A : 2 

ASCII Character Set

Appendix B Portability Considerations 

One fundamental idea when designing OSE Delta was to gather the operating systems for the 

different CPUs together to make it more general. 

The major part of OSE Delta is written in C: only the CPU specific parts and very time-critical parts 

are written in assembler. This results in an easy way to port OSE Delta to any target CPU. The older 

OSE kernels are all written in assembler and are very CPU specific. This can lead to problems when 

porting an application written for an older OSE kernel to OSE Delta. 

Variable sizes 

The biggest problem is if the application is dependent on the size of variables, the OSE types have 

other sizes in OSE Delta than in older OSE kernels. The most obvious examples are the PROCESS 

and SIGSELECT types. Fortunately, applications written in C are usually not dependent on variable 

sizes. 


Link 

Handler 

Debugger 

Interface 

Handlers 

Create_proc 

system call 

OSE Delta 

The link handler mechanism 

is completely new in OSE 

Delta. 

In OSE Delta the debugger 

interface is the same for all 

CPUs. 

Because of CPU dependency 

all the handlers are new in 

OSE Delta. 

The create_proc system call 

in the OSE Classic kernel is 

not part of OSE Delta concept. 

It is however still implemented 

for backwards 

compatibility so it is possible 

to run an application using 

the create_proc system 

call. 

The create_proc system call 

should not be used when 

writing new OSE Delta applications. 

Older OSE kernel 

This means that link handlers 

for older OSE kernels have to 

be able to run in an OSE Delta 

system. 

In older OSE kernels the 

debugger interface is CPU 

dependent, all kernels have different 

debugger interfaces. 

Reference Manual / R1.0.4 OSE / Kernel - Appendix B : 1 

Portability Considerations


Background 

Processes 

Wake_up 

system call 

A prioritized process does 

not have a time slice in OSE 

Delta. Instead there is a separate 

process type called 

background process which 

always run in strict time 

sharing mode on a priority 

level below other processes. 

The background process 

level that exists in the OSE 

Classic kernel is not present 

in OSE Delta. 

Another difference concerning 

background processes is 

that when a background 

process is swapped out before 

the time slice has expired 

the time slice is not 

restarted when it is swapped 

in again as in OSE Classic 

kernels. The background 

process starts executing at 

the place in the time slice 

where it was swapped out. 

The wake_up feature differs 

between older OSE kernels 

and OSE Delta. 

In OSE Delta an interruptprocess 

can be invoked with 

the wake_up feature by 

sending a signal to it. The 

wake_up call informs the 

process what caused the interrupt. 

If not used and a 

signal is sent to an interruptprocess, 

the process will 

start executing anyway. 

The background process concept 

is not present in the OSE 

Classic kernel. Instead there is 

a background process level. 

In older OSE kernels the 

wake_up feature is either aconfiguration 

option or not present 

at all. 

Reference Manual / R1.0.4 OSE / Kernel - Appendix B : 2 

Portability Considerations


Index 

A 


addressee process 3 : 92 

alloc definition 3 : 3 

assign_linkhandler definition 3 : 5 

attach definition 3 : 7 

attach_block definition 3 : 9 


B 

background process 3 : 19, 3 : 20, 3 : 54 

block descriptor 3 : 13, 3 : 75 

block error handler 3 : 15 

block ID 3 : 20, 3 : 32, 3 : 56 

block name 3 : 13 

block owner 3 : 13 

block start 3 : 115 

block status 3 : 13, 3 : 43 

block type 3 : 54 

blocks 

attaching 3 : 9 

attaching a pool to 3 : 17 

block ID 3 : 20, 3 : 32, 3 : 56 

creating 3 : 13 

descriptor 3 : 13, 3 : 75 

killing 3 : 96 

name 3 : 13 

owner 3 : 13 

starting 3 : 115 

status 3 : 13, 3 : 43 

stoping 3 : 118 

breakpoint 3 : 73, 3 : 96 

breakpoints 

clearing 3 : 11 

setting 3 : 96 

byte order 5 : 1 

C 

caller information reference 6 : 12 


CPU registers 3 : 103 

CPU type 3 : 35 






current owner 3 : 87 


D 

data types 4 : 3 

dead process 

breakpoint in 3 : 11, 3 : 96 

detection of 3 : 7 

flushing queue of 3 : 30 

ID of 3 : 32 

sending signals to 3 : 92, 3 : 95 

debugger system calls 









resume 3 : 89 

set_mem 3 : 102 

set_pcb 3 : 103 


detach 3 : 27 

dummy process 3 : 19 

dynamic semaphore 3 : 23 

E 

environment variable 2 : 2, 2 : 7, 3 : 36, 3 : 37, 3 

: 39, 3 : 99, 3 : 100 

environment variables 

reading 3 : 36, 3 : 37, 3 : 39 

setting 3 : 99, 3 : 100 

error 3 : 28, 6 : 12 

error codes 3 : 28, 3 : 29, 6 : 1 

error handler 6 : 1 

system call in progress 6 : 12 

error code 3 : 28, 3 : 29 

error handler 4 : 1, 6 : 1 

block error handler 3 : 15, 3 : 28, 3 : 29 


entrypoint 3 : 14, 3 : 15 

kernel error handler 3 : 15 

level of 3 : 15 

process error handler 3 : 15 

error handler entrypoint 3 : 15 

error level 3 : 15 

Reference Manual / R1.0.4 OSE / Kernel - index : 1 

Index


error messages 6 : 1, 6 : 14, 6 : 15 

error report 3 : 28, 3 : 29 

error2 3 : 29 

F 

fast semaphore 3 : 40, 3 : 101, 3 : 113, 3 : 121 

fast semaphores 


signalling 3 : 113 

value of 3 : 40, 3 : 44 

waiting for 3 : 122 

flush 3 : 30 


G 
























H 

hardware interrupt 3 : 20, 3 : 123 

hardware priority 3 : 123 

hardware vector 3 : 21 

header files 4 : 1, 4 : 3 

hunt 3 : 68 


I 

implementation level 2 : 1, 3 : 130 


intercept status 3 : 89 

interrupt process 3 : 19 

interrupt process priority 3 : 19 

K 

kernel error handler 3 : 15 



L 

link handlers 

assign_linkhandler definition 3 : 5 

byte order 5 : 1 

example of 5 : 13 

header file 4 : 1 

hunt request 3 : 68–3 : 69 

linkname 3 : 5 

signal structure 5 : 1 

linkname 3 : 5 

local pools 3 : 17 

M 

manifest constants 4 : 1 


memory management 



creating a pool 3 : 17 

include files for 4 : 1 

killing segments 3 : 75 

moving memory 3 : 78 

supervising segments 3 : 7 

writing memory 3 : 102 

memory manager 3 : 102 

memory manager block 3 : 78, 3 : 91, 3 : 108 

MMU 3 : 78, 3 : 91, 3 : 108, 3 : 109 

N 

negative receive specification 3 : 81 

NIL 3 : 125 

O 




OS68 3 : 126 

OSE 3 : 129 

OSE_I 3 : 131 


OSSIM 3 : 133 

owner 3 : 3 

P 

phantom process 3 : 19 


Index


pool 

create pool 3 : 17 

local pool 3 : 17 

returning memory 3 : 31 

system pool 3 : 17 

power fail handler 3 : 79 


prioritized process 3 : 19 

priority 3 : 19, 3 : 53, 3 : 104, 3 : 105 

process entrypoint 3 : 19, 3 : 132 

process error handler 3 : 15 

process name 3 : 19 

process start 3 : 89, 3 : 115 

process status 3 : 43 

process stop 3 : 118 

process type 3 : 54 

processes 

background 3 : 19, 3 : 20, 3 : 73, 3 : 89, 3 : 

103, 3 : 115, 3 : 118 

control block 3 : 43, 3 : 102 

creating 3 : 19 

current 3 : 25 

dummy 3 : 19 

entrypoint 3 : 19 

hunting 3 : 68 

identity 3 : 43, 3 : 47 

intercepting 3 : 73 

interrupt 3 : 19, 3 : 73, 3 : 123 

interrupt vector 3 : 20 


name 3 : 19, 3 : 45, 3 : 68 

phantom 3 : 19, 3 : 44 

prioritized 3 : 19, 3 : 89, 3 : 103, 3 : 104, 3 : 

105, 3 : 115, 3 : 118 

priority 3 : 19, 3 : 44, 3 : 53, 3 : 104, 3 : 105 

redirection table 3 : 20, 3 : 106 

resuming 3 : 89 

stack 3 : 19, 3 : 21, 3 : 44 


status 3 : 43, 3 : 73, 3 : 89, 4 : 4 

stoping 3 : 118 

superuser 3 : 13 

suspending 3 : 26 

timer interrupt 3 : 19, 3 : 20, 3 : 73, 3 : 89, 3 

: 115, 3 : 118 

timeslice 3 : 20 

type 3 : 19 

waking up 3 : 123 

programloader 3 : 102 

R 



recieve 3 : 81 

recieve timeout 3 : 85 

redirection table 3 : 92 

remote call server 

header files for 4 : 1 


parameter structure 5 : 4 

signal definition 5 : 1 

remote systems calls 

parameters of 5 : 4 

remote responses 5 : 3 

remote_call_server 3 : 13 

use_remote_calls 3 : 13 

remote_call_server 3 : 13 


resume 3 : 89 

S 

segment descriptor 3 : 10 

segment ID 3 : 10 

segment number 3 : 10 

segments 

attaching 3 : 10 

descriptor 3 : 10 

ID 3 : 10 


numbers 3 : 10, 3 : 108 

select_segment 3 : 91 

semaphores within 3 : 23 


setting mode 3 : 109 

supervising 3 : 7 

supervisor space 3 : 10 

semaphore 3 : 114, 3 : 122 

semaphore value 3 : 57 

semaphores 


dynamic 3 : 23 

killing 3 : 23, 3 : 77 

signalling 3 : 114 

static 3 : 23 

value of 3 : 57 

waiting for 3 : 122 

send 3 : 92 


Index


send_w_s 3 : 95 

sender 3 : 94 

set_bp 3 : 96 




set_mem 3 : 102 

set_pcb 3 : 103 

set_pri 3 : 104 







signal buffer 3 : 3, 3 : 110, 3 : 112 

signal number 3 : 3, 3 : 81 

signal owner 3 : 92 

signal queue 3 : 62, 3 : 81 

signal structs 4 : 3 



signals 

allocating 3 : 3 

attaching 3 : 7, 3 : 127 

detaching 3 : 27 

freeing 3 : 31 

owner 3 : 3, 3 : 31 

receiving 3 : 81, 3 : 83 

redirecting 3 : 92 

remote signals 5 : 1 

restoring 3 : 87 

sending 3 : 92, 3 : 95 

signal addressee 3 : 1 

signal number 3 : 7, 5 : 1 

signal selection 3 : 81, 3 : 83, 3 : 85 

signal sender 3 : 94 

signal structures 4 : 3 

size 3 : 110, 3 : 112 

union signal 4 : 3 


software event 3 : 123 

start 3 : 115 


static semaphore 3 : 23 

stop 3 : 118 

superuser 3 : 111 

superuser processes 3 : 10 

superuser system calls 





set_mem 3 : 102 




tick 3 : 120 

supervise a memory segment 3 : 7 

supervisor space 3 : 10 

system 

shut down 3 : 79 


system calls 


alloc 3 : 3 

assign_linkhandler 3 : 5 

attach 3 : 7 











detach 3 : 27 

error 3 : 28 

error2 3 : 29 

flush 3 : 30 
















Index












hunt 3 : 68 






NIL 3 : 125 




OS68 3 : 126 

OSE 3 : 129 

OSE_I 3 : 131 


OSSIM 3 : 133 


receive 3 : 81 




resume 3 : 89 

selecting 3 : 91 

send 3 : 92 

send_w_s 3 : 95 

sender 3 : 94 

set_bp 3 : 96 




set_mem 3 : 102 

set_pcb 3 : 103 

set_pri 3 : 104 










start 3 : 115 


stop 3 : 118 


system_tick 3 : 119, 3 : 135 

tick 3 : 120 



wake_up 3 : 123 

system clock 

running 3 : 120 

system pool 3 : 17 

system restart 3 : 79 

system start 3 : 117 

system tick 

length of 3 : 119 

system tick counter 3 : 65, 3 : 66, 3 : 135 


system_tick 3 : 119 

T 

tick 3 : 120 

timer-interrupt process 3 : 19 

timeslice 3 : 20 

type definitions 4 : 3 

U 

union signal 4 : 3 

use_remote_calls 3 : 13 

user number 3 : 67 

W 



wake_up 3 : 123 


Index

Kern el

Create successful ePaper yourself

Delete template?

Save as template?