test

ChorusOS 4.0 Introduction

Chapter 2 Using ChorusOS

This chapter introduces the basic principles of using the ChorusOS operating system.

The ChorusOS System Image

The ChorusOS operating system is supplied with two standard images:

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.

Downloading the System Image

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 ]

Basic Environment

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.

Building an Application Actor

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.

  1. Create a working directory where the actor will reside.

  2. In this working directory, create a file named Imakefile containing the following lines:

    Depend(hello.c)
EmbeddedSupActorTarget(hello_s.r,hello.o,)

  3. 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);
}

  4. 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.

  5. Build the dependencies:


    % make depend

  6. Build the application:


    % make

Your directory will now contain a supervisor actor, hello_s.r.

Embedding your Actor in the System Image

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:

Running your Actor in the Basic Environment

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!

Extended Environment

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.

Communicating with the Target Using rsh

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).

Mounting the Host File System

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.

Security

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:

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.

Running the "Hello World" Example

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.

Input/Output Management

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.

System Administration in the Extended Environment

C_INIT Actor

In the extended environment, a special actor called C_INIT provides administrative commands for the following:

Here are the most frequently used C_INIT commands:

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.

System Start-up

At system start-up, the C_INIT actor executes the following steps:

  1. sets up an initial virtual file system

  2. executes commands from the configuration file sysadm.ini

  3. executes commands from /etc/rc.chorus when a root file system is mounted (see C_INIT(1M))

    Note -

    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:

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.

Note -

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.

Initialization Examples

Below are typical commands of the sysadm.ini file.