ChorusOS man pages section 2K: Kernel System Calls

intro(2K)

NAME

Intro- introduction to ChorusOS error codes and system calls

DESCRIPTION

This manual describes the principal ChorusOS APIs. All system calls and other interfaces provided for use by applications are documented here. In this context ``applications'' covers a wide range of functions including device drivers, OS personality emulation servers, real time control programs, and so forth.

FEATURES

Each API function is associated with one or more system features. A given interface is available if, and only if, one of its associated features was configured on the target system when that system was built.

Each manual page has a FEATURES section, where the list of features offering this interface is provided.

The features available in ChorusOS are introduced here. For each feature, there is a man page in the 5FEA section which gives an description of the feature and a list of all interfaces associated with the feature.

DATE

Time of day service.

DDM

Device Driver Manager proxy.

EVENT

Event flag sets.

HOT_RESTART

Management of restartable actors and persistent memory.

IPC

Provide OSI stack entry points.

IPC_REMOTE

Inter-process communication.

IPC_REMOTE_COMM

IPC remote communication.

LAPBIND

Built-in nameserver for local access points.

LAPSAFE

Safe mode for LAP invocations.

LOG

System logging

VIRTUAL_ADDRESS_SPACE

Memory management features.

ON_DEMAND_PAGING

Memory management features.

MIPC

Message queues.

MON

System monitoring.

PERF

Performance support.

RTC

Real-time clock.

RTMUTEX

Real-time mutexes.

ROUND_ROBIN

Scheduler features.

TIMER

System time.

SEM

Semaphores.

USER_MODE

Support for user actors.

VTIMER

Thread execution timing.

POSIX-compliant API features

The following features provide POSIX-compatible functions (1003.1, 1003.1b, 1003.1c).

POSIX-THREADS: POSIX 1003.1c pthread functions.
POSIX-TIMERS: POSIX 1003.1b real-time clock and timer functions.
POSIX_MQ: POSIX 1003.1b real-time message queues.
POSIX_SHM: POSIX 1003.1b real-time shared memory objects.
POSIX_SOCKETS: POSIX 1003.1j (standard BSD compatible) socket functions.

Note -

The POSIX 1003.1c pthread functions and 1003.1b real-time clock and timer functions are delivered into the standard libcx.a library.

ERRORS

Warning: For reasons of compatibility with existing standards, different system calls use distinct error return conventions. Always refer to individual man pages when interpreting error codes.

Most ChorusOS system calls are of the integer type and return a direct value which is zero or positive when the call is successful, and negative to indicate an error. The possible error return values are listed below.

The PRIVATE-DATA calls follow a similar convention (error code returned directly by the function) but the error codes are positive, not negative. PRIVATE-DATA error values are indicated below.

The POSIX-THREADS functions whose names begin with pthread_ follow a similar convention, but with POSIX error return values.

All other POSIX features (POSIX-TIMERS, POSIX_MQ, POSIX_SHM, POSIX_SOCKETS, remaining POSIX-THREADS calls) return -1 in case of error and set the errno variable. Note that errno is not cleared on successive calls, so it should be tested only after an error has been indicated via a function return code. In multi-threaded actors, errno is implemented not as a global variable but as a macro which refers to a per-thread errno value. A complete list of the POSIX error codes (possible errno values) can be found in the file <errno.h>.

Standard ChorusOS error codes

The list of error codes is given below, with general meanings. However, this general definition may be overwritten by certain system calls. The meaning should be interpreted according to the type and the circumstances of the call.

When a thread that executes in supervisor address space performs a system call, the arguments of the call are not fully checked by the system. This applies to threads executing in supervisor actors and to threads executing in user actors when the VIRTUAL_ADDRESS_SPACE feature is disabled. In general, when such a thread invokes a system call with wrong arguments the result may be unpredictable.

The implication is that when a man page states that a system call will return a given error code in a given error situation, this will be fully enforced by the system only for threads executing in user address space. For threads executing in supervisor address space, the error situations may not be detected by the system. In particular this is the case for the K_EFAULT error situations.

0 K_OK No error: The call returned successfully.
-1 K_EINVAL Invalid argument: An invalid argument has been provided.
-2 K_ENOMEM Out of resources: The microkernel has been unable to perform the call due to a lack of resources.
-3 K_ETOOMUCH Message too big: Attempted to send a message body longer than K_CMSGSIZEMAX bytes.
-4 K_ENOPORT Port invalid: The port local identifier is invalid (the port was never created, or was deleted, or has migrated before or during the call).
-5 K_EFAULT Bad address: The microkernel encountered a hardware access fault in attempting to access one of the arguments of the call.
-6 K_ENOTIMP Not implemented: The call, or one of its options, is not implemented in the current version.
-7 K_EUNKNOWN Unreachable destination: Attempt to send an RPC request to an unreachable port.
-8 K_ETIMEOUT Time-out occurred: A system call failed because the time-out occurred.
-9 K_EFAIL Transaction failed: A system call failed because the actor which received the request failed.
-10 K_EABORT Aborted wait: Abortable calls (for example. ipcReceive, ipcCall, threadSuspend) have been interrupted because the waiting thread has been aborted.
-11 K_EFULL System queues saturated: An ipcSend, ipcReply or ipcCall failed because the local destination port queue is full, or the local communication system is saturated.
-12 K_EROUND Alignment error: Attempted to allocate a memory region whose starting address is not aligned to a page boundary.
-13 K_EADDR The address of an argument is invalid: Attempted to allocate a memory region overlapping another.
-14 K_EPRIV Privilege violation: Attempted to perform a forbidden operation.
-15 K_EBADMODE Invalid addressing mode: Attempted to send a message with an invalid addressing mode.
-16 K_ESIZE Size error: The size given in the parameter is incompatible with other parameters.
-17 K_EBUSY Memory locking conflict: Attempted to flush a part of a local cache locked in memory.
-18 K_EABORTRPC Aborted RPC: Aborted a remote IPC notification.
-19 K_EMAPPER Mapper access error: Unable to access a mapper.
-20 K_ENOEMPTY Non empty address space: Attempted to duplicate regions within a non-empty address space.
-21 K_EOFFSET Bad segment offset: Attempted to map an impossible part of a segment.
-22 K_EOVERLAP Region overlapping: Attempted to allocate a memory region that would overlap with another one.
-23 K_EPROT Region access rights violation: Attempted to write in a read-only region.
-24 K_ESPACE Address space violation: Attempted to allocate a region outside the valid range of virtual addresses for the address space.
-25 K_EUNDEF Undefined default mapper: The system default mapper is not defined.
-26 K_EARGS Arguments inconsistent: The combination of a number of the call arguments is inconsistent.
-28 K_EBUSYPORT Port in use: Attempted to migrate a port to which a message handler is attached.
-29 K_ELINKFAILURE Link failure: A remote communication protocol failure has been detected during remote IPC.
-30 K_EBADMSG Invalid message identifier: The message identifier parameter is not a valid message address, or the corresponding message has already been consumed.
-31 K_ENOTAVAILABLE System call not available: Attempted to invoke a system call that is not available within this configuration.

PRIVATE-DATA error codes

0 K_OK No error: The call returned successfully.
1 PD_ENOKEY No more keys available: The key table is full, no more keys can be created.
2 PD_ENOMEM Out of resources: The microkernel has been unable to perform the call because of a lack of resources.
3 PD_EINVAL Invalid argument: An invalid argument has been given.
4 PD_ESERVER Cannot connect to server: The Private Data Manager is not accessible.
5 PD_EUSER Called from user mode

DEFINITIONS AND ARGUMENT TYPES

All system call arguments are integer or pointer sized. In other words, if an argument is described as "a structure ...", it is actually "a pointer to a structure ...". The following argument types may occur in system calls exported by the Core Executive or by any other module, with the semantics indicated and constant option values.

KnCap* actorcap

Usually, actorcap is a pointer to a user memory location which either contains an actor capability (input parameter) or will hold an actor capability (output parameter). As an input parameter, actorcap may contain one of the following special values instead:

K_MYACTOR: Designates the home actor of the calling thread.
K_SVACTOR: Designates the supervisor address space.

KnThreadLid threadli

Usually, threadli is a thread local identifier. Instead, threadli may contain the special value K_MYSELF, which designates the calling thread.

No check is performed on the capability for microkernel calls that require a pointer to a capability and a thread local identifier, if this local identifier is set to K_MYSELF.

The following microkernel calls:

threadAbort(), threadActivate(), threadBind(), threadContext(), threadDelete(), threadName(), threadScheduler(), threadStart(), threadStat(), threadStop(), threadSuspend(), threadResume(), and threadTimes()

Note that the threadAbort() and threadStart() system calls above are strictly reserved for internal use only, and MUST NOT be used by any application.

do not check the capability when K_MYSELF is given as the local thread identifier. Getting K_EINVAL for an invalid capability or K_EUKNOWN for an unknown capability implies to call the above microkernel calls with an invalid thread local identifier as well, otherwise the required operation can return K_OK without checking at all the given capability.

KnTimeVal* waitLimit

This argument is used in system calls that make the calling thread block until an explicit event or action occurs. It allows the caller to control the maximum waiting time and abortability of the wait. Usually, waitLimit is a pointer to a user memory location containing a timeout interval (expressed as a (second,nanosecond) pair, see sysTime(2K)). In this case, if the call blocks, it is ABORTABLE. Instead, waitLimit may contain one of the following special values:

K_NOBLOCK: Specifies a polling call. If the relevant condition is not satisfied immediately, the call returns with an error code and does not wait. The call is NONABORTABLE in the sense that it neither consumes the abort state (if the current thread was previously aborted) nor returns K_EABORT. For compatibility with previous versions of the system K_NOBLOCK has the value 0.
K_NOTIMEOUT: Specifies an unlimited wait. The call is ABORTABLE. For compatibility with previous versions of the system K_NOTIMEOUT has the value -1.
K_NOTIMEOUT_NOABORT: Also specifies an unlimited wait. The call is NONABORTABLE.

Site number

The Chorus microkernel has the concept of "Site Number" which has the following properties

There is a unique Site Number per site.
The site number is a 32 bit unsigned integer
The site Number is embedded into all structures of the type "KnUniqueId" which are associated to the following microkernel entities:
- IPC ports
- IPC Group Capabilities (KnCap)
- Actor Capabilities (KnCap)

The site number of the target is provided to the microkernel when you boot the system and can be provided in two different ways:

By the boot program within the "siteNumber" field of the "bootConf" structure; in this case, it is the responsability of the boot program to determine the site number of the target. The way the site number is found by the boot is fully "boot dependent", and may be specific to the target board. For instance, it may be stored in the "NVRAM" memory, or computed more dynamically from some (unique) board identifier. When the target is booted with the standard ChorusOS network boot monitor, it is the whole IP address used by the boot monitor which is provided as the site number of the target.
Within the boot image through the "chorusSiteId" microkernel tunable; in this case, the site number is statically fixed within the boot image. This approach is less flexible that the case above, as the same boot image cannot be booted on multiple similar target boards. For this reason, it should only be used when there is no way for the site number of the target board to be determined when you boot the system.

Note -

the value fixed through the tunable takes precedence over the value provided by the boot program.
by default, the site number is set to zero. If the REMOTE IPC feature of the microkernel has been configured, a WARNING message is displayed on the console and the REMOTE IPC feature is not activated. In other words, only local ICP communications are enabled when the site number has not been set.

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving

ChorusOS 5.0 Last Revised December 2001