Configuration Tools

The configuration tools allow the configuration of the ChorusOS operating system. They are designed to be flexible enough to be extended to enable the configuration of any other system component (OS or drivers) or even application actors that may be part of the ChorusOS operating system image.

You can use either one of the following configuration tools to view and modify the characteristics of a ChorusOS operating system image:

• The graphical user interface tool for the ChorusOS operating system is called Ews, or Embedded Workshop.

• The command-line interface tool for the ChorusOS operating system is called Configurator.

The Embedded Workshop Graphical Configuration Tool

The graphical configuration tool, Ews, requires Sun Java JDK 1.2 (JAVA 2) to be installed and the location of the Java virtual machine to be in your path.

To start Ews and open an existing configuration file, type:

$ ews -c config-file

The optional config-file specifies the path of the ChorusOS operating system configuration file conf/ChorusOS.xml to open at start-up.

To start Ews without opening a file, type:

$ ews

User Interface Overview

When started, Ews opens a main window, containing a menu bar and toolbar at the top, a navigation tree pane on the left, and an output view pane at the bottom. The rest of the window is occupied by a Multiple Document Interface (MDI) area, which is used to display other windows, like the Properties Inspector, or the Find View (both are described later). These other windows can be resized, moved, or closed just like any other window, but are constrained within the MDI area, and cannot be moved outside.

The main window of Ews is shown in Figure 2-1.

Figure 2-1 Ews User Interface

Navigation Pane

The navigation pane contains two tabbed windows: a Projects tab, which displays any opened configurations as a hierarchical tree, and a Help tab, which displays the online help table of contents.

Within the Project window, every element in the project view tree is represented by a small icon with a name. Right-clicking on an element brings up a floating context menu, which can be used to perform actions such as changing the element's value. Double-clicking on an element opens the main Properties Inspector window in the MDI area.

Within the Help window, selecting an entry in the table of contents displays the appropriate help page in the MDI area.

Other Windows

The Properties Inspector displays the properties of an element, such as its value and description. Some of these properties may be changed.

The Show Children View window displays the sub-element, or first-level child, of a selected element.

The Find window is used to locate an element in the project view tree. Any element can be searched for by specifying a substring of its name or its type. The search can take place from the root, on the entire tree hierarchy, or from the selected element.

Configuring a ChorusOS Operating System Image

Open a Configuration File

The first operation is to open a ChorusOS configuration file (unless the -c option was used on the command line). For this, select the Open option in the File menu. A file selection dialog allows you to select the configuration file to open. The configuration to open is the conf/ChorusOS.xml file located in the configuration directory. Once opened, a new configuration item can be added to the navigation tree.

More than one configuration may be opened in Ews at the same time.

Browse the Configuration Tree

It is possible to browse the configuration by opening the elements in the navigation tree. There are two general kinds of elements in the tree: folders and variables. Folders are used to organize the configuration variables into hierarchical groups. A folder contains child elements that can be variables or folders. Variables are values used to configure the ChorusOS operating system image.

Disabled Elements

Some of the elements in the configuration tree may be grayed-out and cannot be edited. It is still possible to browse them, however. For example, some variables may depend on the presence of a specific feature: if this feature is not selected, and its current value is set to false, the corresponding tunables are disabled.

Disabling of elements in the configuration is controlled by a condition. This is an optional property attached to some elements, and if the condition is evaluated to false, the element is disabled (elements without a condition property are always enabled). If a folder is disabled, all its child elements (folders and variables) are also disabled.

Invalid Elements

A configuration is invalid if there are one or more invalid elements in the configuration tree.

Configuring the Features and Tunables

The features of the ChorusOS boolean variables, and tunables are expressed as either integers or enumerated variables. The following properties for a tunable are visible in the Properties Inspector:

• Name

• Type

• Default value

• Current value

To change the value of a tunable parameter, edit the Current value property.

Setting a ChorusOS Operating System Environment Variable

The values of the ChorusOS operating system image are located in the various Features and Tunables folders. Features expressed as ChorusOS operating system environment variables are contained in the env variable located in the Environment folder. The env variable is a list, where each element represents an environment variable. This list may be empty for a new configuration. It is possible to add, remove or modify environment variables stored in this list.

Adding an Environment Variable

Select the env variable, right-click to display its context menu, and select New Element. The newly created variable is appended to the list (you might need to expand the list to see the new variable). Set the value of the new variable by editing its value field.

Use makeroute to ensure that the paths to variables (plus actors and daemons) are correct. You can then easily add files to the system image using Ews by simply adding files in the application_files list.

Modifying the Value of an Environment Variable

An environment variable is a structured variable containing two fields: a name and a value. The name field stores the name of the environment variable, and the value field stores the value of this environment variable. Edit the value field to change the value of the environment variable.

Deleting an Environment Variable

From the context menu of the environment variable, choose Delete.

Saving the Modified Configuration

After a configuration has been edited, it can be saved. To do this, select the ChorusOS configuration item in the navigation tree (this is the root element of a configuration), and use its context menu. It is also possible to save it using the Save option in the File menu on the main menu bar, or the Save button on the toolbar.

A modified configuration is displayed in red, as a visual warning that the file has changed.

Build the system image, as described in "Rebuilding the System Image" .

Rebuilding the System Image

To rebuild the system image, select the ChorusOS configuration item in the navigation tree, and use the build item in its context menu (or the corresponding toolbar button). If the configuration file has not been saved since it was last modified, the tool will propose saving it, as the configuration must be saved to be built. If the configuration is invalid, it is not possible to build the corresponding ChorusOS operating system image. See "Invalid Elements".

During the build of the system image, various messages generated by the make tools are displayed in the Ews output window.

It is possible to interrupt the build using the stop button on the toolbar. In this case, the system image is not built.

Command-line Configuration Tool

The following sections explain how to use the command-line configuration tool, configurator, for some common tasks.

Displaying the Configuration

The configurator utility provides an option to display the ChorusOS operating system configuration in a web browser in HTML. Within your build directory, type the following command:

$ configurator -display /tmp/ChorusOS.html 

You can then use your browser to navigate through the ChorusOS.html file generated by this command.

Figure 2-2 Microkernel Configuration Displayed in HTML

Selecting a Configuration Profile

Two predefined profiles are provided, as described in "Configuration Files". To select the basic profile, type:

% configurator -p conf/basic

To re-select the extended (default) profile, type:

% configurator -p conf/extended

Adding, Removing, or Listing a Feature

You can use the configurator utility to add, remove, or list a feature.

Adding a Feature

To add a feature, type:

% configurator -set feature_name=true

The status of the feature_name is set to true.

For example, to add the EVENT feature to the default configuration:

% configurator -set EVENT=true

The configurator utility does not handle feature dependencies automatically. If you define an incomplete set of features, an error message is displayed.

Removing a Feature

To remove a feature, type:

% configurator -set feature_name=false

The status of the feature_name is set to false.

For example, to remove the EVENT feature:

% configurator -set EVENT=false 

You can reset the value of a feature to the default as follows:

% configurator -reset EVENT 

The reset command resets the value to the extended profile default.

Listing a Feature

You can check the value of a feature as follows:

% configurator -list features feature_name 

The output lists the feature and its status. If you omit feature_name, all features are displayed:

% configurator -list features

SEM:bool='true'
EVENT:bool='true'
RTMUTEX:bool='false'
TIMER:bool='true'
VTIMER:bool='false'
DATE:bool='true'

You can list a feature in greater detail with the -info option:

% configurator -info features feature_name 

The output lists the feature, its status, possible values and its description. For example:

% configurator -info features NFS_SERVER

NFS_SERVER:bool='false'
Possible values: true|false
Description: NFS server access from target machine

Changing Tunable Parameter Values

Tunable parameters are defined by symbolic names within the ChorusOS operating system components. Symbolic names include dots (.), to maintain compatibility with previous releases of the ChorusOS operating system. An example of a symbolic name is kern.exec.maxCpuNumber, which is a tunable.

The definition of a tunable parameter includes the definition of a default value for this parameter. Integer values of tunable parameters are expressed either as integers or as hexadecimal numbers.

To change the value of a tunable parameter, use:

% configurator -set tunable_name=value

For example, to reconfigure the microkernel to enable the creation of 300 threads:

% configurator -set kern.exec.maxThreadNumber=300

You can check the value of a tunable parameter as follows:

% configurator -list tunable tunable_name

You can list the values of all the microkernel executable tunables as follows:

% configurator -list tunable kern.exec.*

The output lists the microkernel executable tunables and their values:

kern.exec.maxCpuNumber:int='1'
kern.exec.maxActorNumber:int='64'
kern.exec.maxThreadNumber:int='300'
kern.exec.bgStackSiz:int='0x1000'
kern.exec.dflSysStackSize:int='0x3000'
kern.exec.dflUsrStackSize:int='0x4000'
kern.exec.dblFltStackSize:int='0x800'
kern.exec.intrStackSize:int='0x3000'

You can list a tunable parameter in greater detail with the -info option:

% configurator -info tunable tunable_name 

The tunable, its value and its description are displayed:

% configurator -info tunable kern.lap.*

kern.lap.maxLapBindNumber:int='256'
Description: Maximum number of bind LAPs 

kern.lap.maxLapSafeNumber:int='128'
Description: Maximum number of safe LAPs

Modifying the System Environment

The system environment is defined by a set of dynamic parameters. The system environment is a set of name-value pairs, where name and value are character strings. Values for system environment variables can be obtained by the system and applications at runtime using the sysGetEnv(2K) system call.

To display all the system environment variables, type:

% configurator -list env

To set a new environment variable, or change its value:

% configurator -setenv envar=value

Here is an example:

% configurator -setenv MESSAGE='HelloWorld'  

To unset a variable, so that it is removed from the environment, type:

% configurator -resetenv envar

Rebuilding the System Image

After you have finished modifying the configuration, rebuild the system image by typing:

% make chorus