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
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
realtime 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) and in addition the ChorusOS ACTOR_EXTENDED_MNGT, 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 kernel 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 kernel 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 kernel 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.
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 kernel 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 kernel entities:
IPC ports
IPC Group Capabilities (KnCap)
Actor Capabilities (KnCap)
The site number of the target is provided to the kernel 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" kernel 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 kernel 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 |
Description
terminate a c_actor
get a c_actor capability
get configurable system variables
creates a c_actor
get/set c_actor credentials
create an actor
delete an actor
get and/or set the symbolic name of an actor
get and/or set the protection identifier of an actor
get and/or set the privilege of an actor
get the current actor capability
See actorStop(2K)
get the status of all actors on a site
Stop an actor; Start an actor
create a new c_actor
See afexec(2K)
See afexec(2K)
See afexec(2K)
See afexec(2K)
See afexec(2K)
See afexec(2K)
get c_actor's ID
See aload(2K)
kill or restart an actor
See aload(2K)
See aload(2K)
Manage the loading of an actor
activates a c_actor
list all active c_actors
c_actor trace
wait for c_actor to terminate or stop
See await(2K)
translate address to symbolic information
close a dynamic object
get diagnostic information
gain access to a dynamic object file
get the address of a symbol in a dynamic object
attach an
attach an
See eventInit(2K)
initialize an event flag set; Clear events in an event flag set; Post events in an event flag set; Wait for events in an event flag set
See eventInit(2K)
See eventInit(2K)
allocate a port group capability
insert a port into a port group; remove a port from a port group
send an RPC request and wait for the reply
get the current message body
receive a message
reply to the current message
See ipcSave(2K)
Save the current message; Restore a saved message as the current message
send a message
get system information about the current message
build a message target
See svLapCreate(2K)
See svLapCreate(2K)
See svLapCreate(2K)
invoke a lap handler
See svLapBind(2K)
allocates a message from a message space
free a message of a message space
retrieves the first message of a message queue
post a message to a message queue
remove a message from a message queue
create a message space
open a message space
See mutexInit(2K)
initialize a mutex; acquire a mutex; release a mutex; try to acquire a mutex
See mutexInit(2K)
See mutexInit(2K)
return actor-specific values associated with keys
create a private key for an actor
delete an actor private key
set the actor's key to a specific value
create a port; declare a port
See portCreate(2K)
delete a port
Enable a port portDisable; Disable a port
See portMigrate(2K)
See portUi(2K)
Migrate a port; Get a port sequence number
get and/or set the protection identifier of a port
Get the unique identifier of a port, given its local identifier; Get the local identifier of a port, given its unique identifier
return a thread-specific errno address
return thread-specific value associated with key
create a thread-specific data key
delete a thread-specific data key
return a thread-specific data value for another thread
set a thread-specific data value for another thread
set a thread-specific value
delete all thread-specific values and call destructors
return the thread ID
allocate a region in an actor address space
duplicate an actor address space
deallocate regions of an actor address space
allocate a region in an actor address space and initialise it from another region
create a region in an actor address space and map another region to it
create a region in an actor address space and map (on demand) to it physical memory specified by the caller
Change inheritance options associated with a region; Change paging options associated with a region; Change inheritance options associated with a region; Change opaque values associated with a region
change protection options associated with a region
get the statistics of a region of an actor address space
See rtMutexInit(2K)
Initialize a realtime mutex; Acquire a realtime mutex; Release a realtime mutex; Try to acquire a realtime mutex
See rtMutexInit(2K)
See rtMutexInit(2K)
scheduling classes administration
initialize a semaphore; wait on a semaphore; signal a semaphore
See semInit(2K)
See semInit(2K)
See svExcHandler(2K)
Connect an actor abort handler; Disconnect an actor abort handler; Get an actor abort handler
Connect an actor exception handler; Disconnect an actor exception handler; Get an actor exception handler
Actor stop handler management: Connect an actor stop handler; Disconnect an actor stop handler; Get an actor stop handler
Set an actor's virtual timeout; Cancel an actor's virtual timeout
Copy from trap caller space; Copy string from trap caller space; Copy to trap caller space
See svCopyIn(2K)
See svCopyIn(2K)
Define an exception handler; Define an abort handler
get handler invoker
bind a symbolic name to a lap descriptor; unbind the symbolic name bound to a lap descriptor; get a lap descriptor from a lap symbolic name
create a lap; reset a lap descriptor; test if a lap descriptor has been initialized; duplicate a lap descriptor
delete a lap
See svLapBind(2K)
Disable interrupt processing; Enable interrupt processing; Reenable interrupt processing
Initialize a spin lock; Disable interrupts and acquire a spin lock; Try to disable interrupts and acquire a spin lock; Release a spin lock and enable interrupts; Initialize a spin lock; Acquire a spin lock; Try to acquire a spin lock; Release a spin lock
Copy from supervisor caller space; Copy to supervisor caller space
See svMemRead(2K)
Connect/disconnect a message handler; Prepare a reply to a handled message
See svMsgHandler(2K)
supervisor address space memory allocator
get system context table address
trigger the invocation of the panic handler
Request a timeout; Cancel a timeout; Get timeout resolution
See svSysTimeout(2K)
See svSysTimeout(2K)
Connect a trap handler; Disconnect a trap handler; Get a trap handler
Set a thread's virtual timeout; Cancel a thread's virtual timeout
See svSysTimeout(2K)
Connect a trap handler; Disconnect a trap handler
See svMaskAll(2K)
See svMaskAll(2K)
Set a virtual timeout; Cancel a virtual timeout
kernel benchmark utility
Get Chorus module configuration value
Get a value from the Chorus configuration environment
log a message in the kernel's cyclical buffer
See sysRead(2K)
Read characters from the system console; Write characters to the system console; Poll characters from the system console
request a reboot of the local site
Set a value in the ChorusOS configuration environment
shut down or restart the system
get system time; get system time resolution
See sysTime(2K)
system timer management
See sysTimer(2K)
See sysTimer(2K)
See sysTimer(2K)
See sysTimer(2K)
See sysTimer(2K)
See sysTimer(2K)
delete a value from the ChorusOS configuration environment
See sysRead(2K)
Abort a thread; Check whether the current thread has been aborted
See threadAbort(2K)
make a thread active
bind a thread to a processor
get and/or set the context of a thread
create a thread
delay the current thread
delete a thread
Get the current thread's valid soft register value; Reset the current thread's valid soft register value
get and/or set the symbolic name of a thread
get and/or set thread scheduling parameters
get the current thread local identifier
Initialize a thread semaphore; Signal a thread semaphore; Wait on a thread semaphore
Stop a thread; Start a thread
obtain the descriptions of the threads running in an actor
See threadStart(2K)
See threadLoadR(2K)
Suspend a thread; Resume a thread
get thread execution time
create a timer
delete a timer
get the timer resolution
start, cancel or query a timer
initialize a timer thread pool
wait for a timer expiration event
Build a user-defined unique identifier; Clear a unique identifer; Compare two unique identifers; Extract the site number from a unique identifier; Check a unique identifier's locality; Get a pre-defined site unique identifier; Check whether an unique identifier has been cleared
See uiBuild(2K)
See uiBuild(2K)
See uiBuild(2K)
See uiBuild(2K)
get the local site number
See uiBuild(2K)
See uiBuild(2K)
Get time-of-day; Set time-of-day; Adjust time-of-day univTimeGetRes; Get time-of-day resolution
See univTime(2K)
See univTime(2K)
get virtual time resolution
copy data between actor address spaces
free memory
Fix data in memory; Data in memory
get the minimum allocatable memory block size
get the physical address corresponding to a virtual address
set the memory management parameters
get memory management statistics
See vmLock(2K)
NAME | DESCRIPTION | FEATURES | ERRORS | DEFINITIONS AND ARGUMENT TYPES | ATTRIBUTES |