This chapter introduces the basic principles of using the ChorusOS operating system.
The ChorusOS operating system is supplied with two standard images:
kernonly
, which contains the kernel only and provides a minimal base for porting
chorus
, which contains a full system image allowing configuration of the whole feature set
Refer to the appropriate book in the ChorusOS 4.0 Target Family Documentation Collection for information about building the kernonly
and chorus
system images from the distribution.
Follow the boot instructions specific to your target, as described in ChorusOS 4.0 Installation Guide. Messages similar to the following are displayed:
ChorusOS r4.0.0 for Intel x86 - Intel x86 PC/AT Copyright (c) 1999 Sun Microsystems, Inc. All rights reserved. Kernel modules : CORE SCHED_FIFO SEM MIPC IPC_L MEM_PRM KDB TICK MON ENV \ ETIMER LOG LAPSAFE MUTEX EVENT UI DATE PERF TIMEOUT LAPBIND DKI MEM: memory device 'sys_bank' vaddr 0x7bc43000 size 0x189000 [messages from IOM] Copyright (c) 1992-1998 FreeBSD Inc. Copyright (c) 1982, 1986, 1989, 1991, 1993 The Regents of the University of California. All rights reserved. max disk buffer space = 0x10000 /rd: sun:ram--disk driver started C_INIT: started [ messages from C_INIT and other boot actors ]
In the basic environment, application actors are loaded at boot time as part of the system image. These actors are also known as boot actors.
When the system boots, actors included in the system image are loaded. For each actor, a thread is created and starts running at the actor's program entry point.
This section assumes that you have built a chorus
or kernonly
system image in the build_dir directory. This example will create a simple Hello World
actor.
Create a working directory where the actor will reside.
In this working directory, create a file named Imakefile containing the following lines:
Depend(hello.c) EmbeddedSupActorTarget(hello_s.r,hello.o,)
Create a file named hello.c containing your Hello World program, written in C. For example:
#include <stdio.h> int main() { printf("Hello World!\n"); return(0); }
Generate a Makefile to build the actor, by typing the following command:
% ChorusOSMkMf build_dir/Paths |
See ChorusOSMkMf(1CC) for more information about creating a Makefile.
Build the dependencies:
% make depend |
Build the application:
% make |
Your directory will now contain a supervisor actor, hello_s.r.
The easiest way to add the actor to the system image is to use the graphical configuration tool, ews. See "Adding an Actor to the ChorusOS System Image" for a step-by-step guide on how to do this.
Alternatively, you can modify conf/mkimage/applications.xml so that it contains the list of applications that will be included in your archive. For example, to include your supervisor actor, hello, the content should be as follows:
<folder name='Applications' visible='yes'> <description>Placeholder for customer applications</description> <definition name='hello' configurable='yes'> <description>simple hello actor, in supervisor mode</description> <type name='File' /> <value field='path'> <vstring>absolute_path_to_my_actor/hello_s.r</vstring> </value> <value field='bank'><ref name='sys_bank' /></value> <value field='binary'><ref name='supervisor_actor_model' /></value> </definition> <definition name='application_files' configurable='yes'> <description>application system image files</description> <condition> <or> <equal><var name='SYSTEM' /><const>chorus</const></equal> <equal><var name='SYSTEM' /><const>kernonly</const></equal> </or> </condition> <type name='FileList'/> <value index='size'><ref name='hello' /> </value> </definition> </folder>
Rebuild the system image using one of the following commands:
If you want to build a kernel-only system, type:
% make kernonly |
If you want to build a complete chorus system, type:
% make chorus |
If you want to rebuild the system that you have previously built, type:
% make build |
Boot the system you have created on the target system. For detailed instructions, see the appropriate book in the ChorusOS 4.0 Target Family Documentation Collection.
After the system boots, the following message is displayed on the console:
Hello World! |
The extended environment is provided in the ChorusOS 4.0 release and comes with a special actor called C_INIT
which is dedicated to administrative commands.
Within the extended environment, application actors can either be loaded at boot time, as described in the previous section, or dynamically using the C_INIT
loading facility. Dynamic loading of actors is described in "Running the "Hello World" Example".
The conf/sysadm.ini file is used to specify system initialization commands. Each entry of this file is a command to be executed by C_INIT
during the kernel boot. Typical operations in sysadm.ini are network configuration, device initialization, file system mount. See "System Administration in the Extended Environment" for details.
The sysadm.ini file is not accessed remotely at boot time but is included in the system image.
When the ChorusOS operating system image including the RSH
feature is booted on the target machine, the C_INIT
daemon interprets the commands sent from the host through rsh (see the rshd manpage on your host). For example, to list the options available, type:
% rsh target help |
The following information is displayed by the C_INIT
actor:
C_INIT ChorusOS 4.0.0- valid commands that deal with: File Systems: mount [[-t nfs|ufs|msdosfs|pdevfs] host:pathname|special_file [mount_point]] umount [-v|-F|-f|-a|-t nfs|ufs|msdosfs|pdevfs] [special_file] swapon [mount_point] Actors: arun [-g rgid] [-S | -U] [-k] [-T] [-d] [-q] [-D] [-Z] [-xip] path [args] akill [-s site] {-g rgid | [-c] aid } aps umask [mode] ulimit [-HSafn] [limit] Environment variables: setenv var value unsetenv var env Networks: route netstat ping host ifconfig ifwait ifname [timeout, default infinite] rarp ethernet_interface_name pppd pppclose device pppstop ethIpcStackAttach [dtreepath] Devices: mknod name [b | c] major minor dtree mkdev name unit [dtreepath] This Target: reboot restart memstat This shell: echo string source filename sleep [time in seconds, default=1s] help console rshd chorusStat shutdown -i 0|1|2|3 |
For details of these commands, see C_INIT(1M).
The NFS root file system to be mounted on the target is generated in the ChorusOS operating system build directory by the command:
% make root |
This command populates the build directory with the root directory that contains binary and configuration files to be accessed by the target system.
At start-up, the C_INIT
daemon reads the sysadm.ini configuration file and executes all the commands. See sysadm.ini(4CC) for more information. This configuration file may contain instructions to mount the root file system. For example:
% mount hostaddr:chorus_root_directory / |
If there are no root file system mount instructions in your sysadm.ini file, you must mount the root file system explicitly from the shell:
% rsh target mount hostaddr:chorus_root_directory / |
where target is the name of the target, or its IP address, hostaddr is the IP address of the NFS host in decimal form (for example 192.82.231.1), and chorus_root_directory is the path of the target root directory on the NFS host (for example /home/chorus/root).
When the mount of the root file system is successful, the C_INIT
daemon displays, for example, the following message:
C_INIT: 192.82.231.1:/home/chorus/root mounted as root file system
The next message from C_INIT
depends on whether the /etc/security file exists in the target root directory /home/chorus/root. If /etc/security exists, C_INIT
displays:
C_INIT: system in secured mode
If /etc/security does not exist, C_INIT
displays:
C_INIT: notice - system not in secured mode
You can check that the root file system is mounted using:
% rsh target mount |
Make sure that the file system containing the /home/chorus/root directory can be accessed by NFS from the remote ChorusOS target.
The C_INIT
daemon authenticates users issuing commands from the host.
The ChorusOS operating system can be configured in secure mode, where remote host access is checked through the /etc/security administration file, located on the target root file system (see security(4CC)). In addition, users' credentials may be specified in this file, overriding default C_INIT
configuration values.
If an /etc/security file exists, it must have read permissions for everybody to allow C_INIT
to read it with the default credentials (user identifier 0 and group identifier 0). Secure mode will then be activated. In this mode, C_INIT
authenticates every command it receives from the host. Authentication will fail for two reasons:
The user name of the remote user which issued the rsh command is not found in the security file.
The remote host from which the rsh command came is not in the remote host's list of users.
In this case, a permission denied message is sent back to the host and the command is aborted.
If the authentication procedure succeeds, the user's privilege credentials (user identifier or uid, group identifier or gid and additional groups) are read from the security file. Trusted users have access to the full set of C_INIT
commands.
In non-secured mode, every user is treated as a trusted user and inherits the C_INIT
default credentials (uid 0 and gid 0). In this case, if the host machine has exported the file system to be mounted with the default mapping of root to nobody
, it is necessary that read and execute permissions for the target executable files be given to everybody. Otherwise C_INIT
will not have the right to execute the application binaries.
Another way to circumvent this problem is by inhibiting that mapping of root to nobody
on the host. Please consult your system administrator about this.
Copy your executable application files into the chorus_root_directory/bin directory.
% cp hello_s.r chorus_root_directory/bin |
This step is important as the applications must be in a directory on the host that is exported to the target system.
To start the hello supervisor actor:
% rsh target arun /bin/hello_s.r |
The arun command returns the actor identifier (aid) of the new actor:
Started aid = 13 Hello World! |
To list the actors running on the target:
% rsh target aps |
To kill the actor, the id of which is aid:
% rsh target akill aid |
To display information about current memory usage:
% rsh target memstat |
The ChorusOS operating system actors are loaded and locked in memory when they start. This means that physical memory for the actor's text, data and stack must be available at load time. The memstat command of C_INIT(1M) can be used to check whether enough physical memory is available on the target system.
When actors use the ChorusOS Console Input/Output API, all I/O operations (such as printf() and scanf()) will be directed to the system console of the target. Note that in the basic environment this API is the only one available.
If an actor uses the ChorusOS POSIX Input/Output API and is spawned from the host with rsh, the standard input and output of the application will be inherited from the rsh program and sent to the terminal emulator on the host on which the rsh command was issued.
In fact, the API is the same in both cases, but the POSIX API uses a different file descriptor.
Any extended actor has access to two special files /dev/console and /dev/null. /dev/console always refers to the system console of the target.
Note that select(2POSIX), stat(2POSIX), and fstat(2POSIX) are not supported on the /dev/console and /dev/null devices, and there is no tty
line discipline management for these devices.
In the extended environment, a special actor called C_INIT
provides administrative commands for the following:
network configuration, such as defining IP addresses and initializing network interfaces
file system management, such as partitioning a disk and mounting a file system
device management, such as binding a high level service (file system, networking, tty
management) to an actual device driver
Here are the most frequently used C_INIT
commands:
mknod: defines special device files
mkdev: binds high level services to an instance of a device driver
mount, umount: mounts and unmounts file systems
arun: launches executables
ifconfig: defines IP addresses
route, rarp, netstat, ppp, ping: miscellaneous networking commands
memstat, chorusStat: prints system statistics
setenv, unsetenv, echo, help, sleep, reboot, shutdown: miscellaneous system commands
rshd, console, source: specifies the device from which commands can be accepted:
rshd: from a host through rsh
console: from system console
source: from a file
See C_INIT(1M) for a complete description.
These commands are invoked at system start-up, described in the following section, and later during the life of the system. During the life of the system, the C_INIT
actor executes commands from the system console, or from a remote host through rsh.
At system start-up, the C_INIT
actor executes the following steps:
sets up an initial virtual file system
executes commands from the configuration file sysadm.ini
executes commands from /etc/rc.chorus when a root file system is mounted (see C_INIT(1M))
If the target has a valid IP address, the file /etc/rc.chorus.<ip_address> (if it exists) will be selected instead of /etc/rc.chorus. <ip_address>
must be written in the usual dot notation, for example: 192.82.231.1.
The initial virtual file system in step 1 contains only two directories, /dev and /image/sys_bank. The /dev directory, initially empty, is used for the definition of special devices, like /dev/tty01. The /image/sys_bank directory contains all the components in the boot image:
system actors such as am
, iom
, C_INIT
and drivers
system configuration files (sysadm.ini)
user defined configuration files and executables
All of these components can be accessed like the files in an ordinary file system, using their path, for example: /image/sys_bank/sysadm.ini.
To access /dev and /image directories on the virtual file system, dev and image directories must be present on your root file system, and this root file system must be mounted.
In step 2, the C_INIT
actor executes commands from a configuration file called sysadm.ini. This file contains all the commands needed for the initial administration of the system, including networking, file system management and device management.
The sysadm.ini file can be customized. On the host, it is located in the conf subdirectory of the ChorusOS build directory. This file is automatically embedded in the boot image, in the /image/sys_bank/sysadm.ini file of the initial file system. This allows you to configure embedded targets which do not have access to a local or remote file system.
Below are typical commands of the sysadm.ini file.
Associate ifnet interface 0
to a specific Ethernet driver:
% mkdev ifeth 0 /pci/epic/epic100 |
The pathname is optional. For more information, refer to mkdev(1M).
In the ChorusOS operating system, hardware devices are identified by a path in a device tree; the mkdev command connects to the driver instance servicing the indicated hardware device.
Associate ifnet interface 0
to the first Ethernet driver found:
% mkdev ifeth 0 |
Define the IP address of ifnet interface 0
:
% ifconfig ifeth0 ip-address netmask ip-mask broadcast broadcast-addr |
Define the IP address using the rarp
protocol on ifnet interface 0
:
% rarp ifeth 0 |
Associate a special device to a serial line driver:
% mknod /dev/tty01 c 0 0 % mkdev tty 0 /pci/pci-isa/ns16550-2 |
The third argument to mknod, 0, is the major device number identifying the serial line driver. The fourth argument to mknod, 0, is the minor device number identifying the hardware device at the POSIX level.
Mount a local file system by defining required devices, then mount the disk:
% mknod /dev/sd0a b 10 0 % mknod /dev/rsd0a c 9 0 % mount /dev/sd0a / |
See also "Automated File System Initialization" in the ChorusOS 4.0 File System Administration Guide.
Mount a remote file system:
% mount host-ip-addr:host-path / |