ChorusOS 5.0 Source Delivery Guide

Adding Features and Tunables

This section demonstrates through examples how to add new features and tunables to the ChorusOS operating system.

Adding a Tunable

Define the Tunable

To add a tunable (my_tunable) to the OS component, write an integer named my_tunable in an OS source file, as follows:
```
extern int my_tunable;
```
This integer is configured using the external name iom.my.tunable. The default value for my_tunable is 0.

Add the Tunable to the XML Source Configuration File

To add the tunable to the XML source configuration file for the OS component, go to the directory containing the OS configuration files:
```
host% cd source_dir/os
```

Modify sys_rule.xml and sys_action.xml

To add the iom.my.tunable, you must modify two files, sys_rule.xml and sys_action.xml.
- The sys_rule.xml file contains the description of the configurable entities as features and tunables, and their associated dependency.
- The sys_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 sys_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 OS tunables in sys_action.xml:
```
 <setting name="sys.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 build_dir
host% rm conf/mkconfig/sys_rule.xml conf/mkconfig/sys_action.xml
host% make xml
```

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

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

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

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

Adding a Feature

Features are implemented by source code modules. The example below demonstrates how to use modules to add a feature, called TEST, to your ChorusOS operating system. In this feature, we shall include a test file, mytest.c.

Create a test directory

host% cd source_dir/os/sys
host% mkdir test

Create the a modules.df file in this directory
```
MODULES=bsd__test
```

Create mytest.c and common.mf files

mytest.c:
#include <stdio.h>


int hello()
{
  printf("hello world\n");
  return 0;
}

common.mf:
C__SRCS = \
        mytest.c

Add the TEST feature to the sys_action.xml and sys_rule.xml files

Add the following to sys_action.xml:

sys_action.xml:
<!--
bsd__test=on/off
-->
  <setting name="iom.modules"/>

    <description/>bsd__test/<description>
    <condition>

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

      <const>bsd__test/<const>
    /<value>
  /<setting>

Add the following to the sys_rule.xml file:

sys_rule.xml:
  <feature name="TEST">

      <description> TEST /<description>
      <false>
    /<feature>

Build the TEST feature

Since the XML configuration files have been modified, you must propagate the changes. The existing sys_action.xml, and sys_rule.xml files must be updated.
```
host% cd build_dir
host% rm conf/mkconfig/sys_rule.xml conf/mkconfig/sys_action.xml
host% make xml
```

Check that the TEST feature is present

host% build-DEVTOOLS/host/bin/configurator -list features | grep TEST
TEST:bool='false'

Assert the TEST feature

host% build-DEVTOOLS/host/bin/configurator -set TEST=true

Building the test directory

Before building a new archive with the TEST feature asserted, merge the source code corresponding to TEST within the working environment:
```
host% cd build_dir/build-OS/src
host% ../../build-DEVTOOLS/host/bin/mkmerge -U
host% cd build_dir
host% make mkmk
```
To perform the merge, you must first run mkmerge in build-OS/ to perform a merge update, then run make mkmk in build_dir.

Compile the system to produce an new archive with the TEST feature
```
host% make
host% make chorus
```

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 OS component contains:

OS_XML = os.xml sys_rule.xml sys_action.xml cinit.xml cinit_action.xml 
hrCtrl.xm
l hrCtrl_action.xml
OS_SYSADM = sysadm.ini


xml:: DEVTOOLS.all $(OS_DIR)/exports.lst
    @sh $(DEVTOOLS_DIR)/cpxml $(BUILD_DIR)/conf/mkconfig $(OS_DIR)/conf/
    mkconfig $(OS_XML)
    @sh $(DEVTOOLS_DIR)/cpxml $(BUILD_DIR)/conf $(OS_DIR)/conf $(OS_SYSADM)
    @sh $(DEVTOOLS_DIR)/cpxml $(OS_DIR) $(OS) Makefile.bin

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