Chapter 6 Customization

ChorusOS Configuration

ChorusOS 4.0 Introduction explains how to configure the ChorusOS operating system with the configurator command, or by using the ews graphical tool. With both configuration tools, you can statically configure the features, tunables and environment variables. Once the system configuration has been altered, rebuild a new system image.

Note -

It is strongly advised that you use the ews graphical tool, particularly if you are not familiar with the configurator command, as the ews graphical tool ensures the ChorusOS system integrity.

This chapter explains how to implement the features and tunables managed by the mkmk tool.

Features control the list of modules linked to build an actor. The list of object files used to link an actor is calculated from the values of the features values.
Tunables provide a way of changing the values of integers used in the actor. There is no recompilation of the source files. Values are taken into account when the actor is linked.

Only components built with the mkmk tool can implement features and tunables. Features and tunables apply to configurable actors in which the ChorusOS kernel itself is included.

Configuration files are all expressed in eXtensible Markup Language (XML). This provides a structured and organized view of the various configuration options of the ChorusOS system. See ChorusOS 4.0 Introduction for a description of the XML configuration language, as used in the ChorusOS system.

Adding a Tunable

To add a tunable (my_tunable) to the IOM component, an integer named my_tunable needs to be written in an IOM source file, as follows:

extern int my_tunable;

You will configure this integer using the external name iom.my.tunable. The default value for my_tunable is 0.

Execute the following steps:

To add the tunable to the XML source configuration file for the IOM component, go to the directory containing the IOM configuration files:
```
host% cd <src_dir>/iom/conf/mkconfig
```
To add the iom.my.tunable, modify two files, iom_rule.xml and iom_action.xml.
- The iom_rule.xml file contains the description of the configurable entities as features and tunables, and their associated dependency.
- The iom_action.xml file contains the internal implementation rules for management of features and tunables and provides the interface with the mkmk environment.
Include the definition of the tunable in XML in the iom_rule.xml file.
```
<tunable name="iom.my.tunable">
     <description> My Tunable </description>
     <int>
     <const>0</const>
     </tunable>
```
This definition includes the external name, a description field that will be accessible through the ews configuration tool, and a default value. All tunable values are integers; the default value is 0 in this example.

Include the standard rule used for the management of the IOM tunables in iom_action.xml:
```
 <setting name="iom.tunables">
<condition><ifdef name="iom.my.tunable"></condition>
<value index="size">
<vstring>my_tunable iom.my.tunable ${iom.my.tunable}</vstring>
</value>
</setting>
```
Note -
iom.my.tunable is the external name of the tunable and my_tunable is the corresponding integer declaration in the source code.
Update the configuration in the build directory and build the new system image. As you modified XML configuration files in the source directory, you must propagate these changes back to the work directory. Remove the corresponding XML files and run make xml.
```
host% cd <work_dir>
host% rm conf/mkconfig/iom_rule.xml conf/mkconfig/iom_action.xml
host% make xml
```

Set your tunable and check that it is now visible in the configuration:

host% configurator -set myiom.my.tunable=0x12345
host% configurator -list tunables | grep my
         myiom.my.tunable:'0x12345'

Build the new system image and check that the tunable is in the IOM actor:

host% make build
host% powerpc-elf-nm image/RAM/chorus/bin/N_iom | grep my_ 
a00b44f0 D my_tunable
	 a00b44f0:       00 01 23 45     .long 0x12345

Adding a Feature

A module is source code which implements a feature. Create a file test.c as shown for the creation of bye.c in the mkmk tutorial in Chapter 5, Creating a ChorusOS Component. The module may be created so that it will (or will not) be present in the IOM component. This depends on the value of the feature MY_TEST. By default, the module will not be included in the IOM component, as explained below.

To create the test module, carry out the following steps:

Create the test.df production file for the test module:
```
host% cd <src_dir>/iom/src/os/iom/sys/test
```
Create a test.df file containing:
```
   MODULES=module_test
```
The module named module_test will contain any object files present in the directory and subdirectories. The module is a collection of object files, in this example, it will only contain test.o.
To add the feature in the XML source configuration file for the IOM component, go to the directory containing the IOM configuration files:
```
host% cd <src_dir>/iom/conf/mkconfig
```
In order to add the MY_TEST feature, modify both of the iom_rule.xml and iom_action.xml files. Include the definition of the feature in XML in the iom_rule.xml file:
```
 <feature name="MY_TEST">

           <description> My Feature </description>
           <bool>
           <false>
         </feature>
```
The definition includes the name of the feature, a description field and a value. Both the description field and the value will be accessible through the ews configuration tool. In this example, the value is a boolean value, false by default. As the default value is false, the module will not appear in the IOM component. Include the standard rule used for the management of the IOM features in the iom_action.xml file:
```
<setting name="iom.modules">

         <description>module_test</description>
         <condition>

           <var name="MY_TEST">
         </condition>
         <value index="size">

           <const>module_test</const>
         </value>
         </setting>
```
Note -
MY_TEST is the external name of the feature, module_test is the corresponding module managed by the mkmk tool.

Rebuild the IOM component:

host% make mkmk
host% make depend
host% make

Update the configuration in the build directory and build the new system image:
```
host% cd <work_dir>
host% rm conf/mkconfig/iom_rule.xml conf/mkconfig/iom_action.xml
host% make xml
host% make build
```
As the newly created test module is set to FALSE by default, you will not find the definition of my_tunable by running:
```
host% powerpc-elf-nm image/RAM/chorus/bin/N_iom | grep my_
```
In order to configure the MY_TEST feature, type:
```
host% configurator -set MY_TEST=true
```
and the test module will be integrated.

Adding a New XML File

XML files used during ChorusOS system generation are copied to the conf directory, so that they can be modified using the configurator command or the ews graphical tool. A component that adds new XML files must have rules to execute these files in its Makefile.bin file. For instance, the Makefile.bin of the IOM component contains:

IOM_XML = iom.xml iom_rule.xml iom_action.xml

xml:: DEVTOOLS.all $(IOM_DIR)/exports.lst
sh $(DEVTOOLS_DIR)/cpxml $(BUILD_DIR)/conf/mkconfig $(IOM_DIR)/conf/mkconfig $(IOM_XML)

In this example, the XML files have to be copied from the IOM merged tree, so the XML target depends on $(IOM_DIR)/exports.lst (which is produced by mkmerge during the IOM merge). The cpxml command acts as a wrapper around cp.

The conf/ChorusOS.xml file includes, directly or indirectly, all the XML files used during the ChorusOS system generation. This file is generated automatically. As the inclusion order of XML files is important, the generation of conf/ChorusOS.xml uses the XML0, XML1, XML2 and XML3 make variables in that order. In other words, files in XML0 are included in ChorusOS.xml, before files in XML1.

For instance, the Makefile.bin of the IOM component contains:

XML3 += mkconfig/iom.xml

For further information on XML files, see Chapter 7, XML Syntax.