NAME | DESCRIPTION | FEATURES | ERRORS | DEFINITIONS AND ARGUMENT TYPES | ATTRIBUTES
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.
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.
Time of day service.
Device Driver Manager proxy.
Event flag sets.
Management of restartable actors and persistent memory.
Provide OSI stack entry points.
Inter-process communication.
IPC remote communication.
Built-in nameserver for local access points.
Safe mode for LAP invocations.
System logging
Memory management features.
Memory management features.
Message queues.
System monitoring.
Performance support.
Real-time clock.
Real-time mutexes.
Scheduler features.
System time.
Semaphores.
Support for user actors.
Thread execution timing.
The following features provide POSIX-compatible functions (1003.1, 1003.1b, 1003.1c).
POSIX 1003.1c pthread functions.
POSIX 1003.1b real-time clock and timer functions.
POSIX 1003.1b real-time message queues.
POSIX 1003.1b real-time shared memory objects.
POSIX 1003.1j (standard BSD compatible) socket functions.
The POSIX 1003.1c pthread functions and 1003.1b real-time clock and timer functions are delivered into the standard libcx.a library.
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>.
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.
The call returned successfully.
An invalid argument has been provided.
The microkernel has been unable to perform the call due to a lack of resources.
Attempted to send a message body longer than K_CMSGSIZEMAX bytes.
The port local identifier is invalid (the port was never created, or was deleted, or has migrated before or during the call).
The microkernel encountered a hardware access fault in attempting to access one of the arguments of the call.
The call, or one of its options, is not implemented in the current version.
Attempt to send an RPC request to an unreachable port.
A system call failed because the time-out occurred.
A system call failed because the actor which received the request failed.
Abortable calls (for example. ipcReceive, ipcCall, threadSuspend) have been interrupted because the waiting thread has been aborted.
An ipcSend, ipcReply or ipcCall failed because the local destination port queue is full, or the local communication system is saturated.
Attempted to allocate a memory region whose starting address is not aligned to a page boundary.
Attempted to allocate a memory region overlapping another.
Attempted to perform a forbidden operation.
Attempted to send a message with an invalid addressing mode.
The size given in the parameter is incompatible with other parameters.
Attempted to flush a part of a local cache locked in memory.
Aborted a remote IPC notification.
Unable to access a mapper.
Attempted to duplicate regions within a non-empty address space.
Attempted to map an impossible part of a segment.
Attempted to allocate a memory region that would overlap with another one.
Attempted to write in a read-only region.
Attempted to allocate a region outside the valid range of virtual addresses for the address space.
The system default mapper is not defined.
The combination of a number of the call arguments is inconsistent.
Attempted to migrate a port to which a message handler is attached.
A remote communication protocol failure has been detected during remote IPC.
The message identifier parameter is not a valid message address, or the corresponding message has already been consumed.
Attempted to invoke a system call that is not available within this configuration.
The call returned successfully.
The key table is full, no more keys can be created.
The microkernel has been unable to perform the call because of a lack of resources.
An invalid argument has been given.
The Private Data Manager is not accessible.
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.
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:
Designates the home actor of the calling thread.
Designates the supervisor address space.
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.
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:
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.
Specifies an unlimited wait. The call is ABORTABLE. For compatibility with previous versions of the system K_NOTIMEOUT has the value -1.
Also specifies an unlimited wait. The call is NONABORTABLE.
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.
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.
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
Interface Stability | Evolving |
NAME | DESCRIPTION | FEATURES | ERRORS | DEFINITIONS AND ARGUMENT TYPES | ATTRIBUTES