Chapter 7 XML Syntax

This Chapter gives a formal description of the XML language used in the ChorusOS configuration files.

The conf directory described throughout this document includes several XML files that you can use as examples when you need to modify the XML configuration files. The ChorusOS 4.0 Porting Guide also explains how to modify the XML configuration files when adapting ChorusOS to a new target platform.

XML Files

The grammar given here is a simplified overview of the ECML language. ECML is a language based on XML. The ECML DTD is located in <bin_dir>/tools/ews/ChorusOS.dtd file.

Table 7-1 Semantics of Grammar in XML Files

[ a ]	means that the a element is optional and can be omitted
{ a | b }	means that either the a element or the b element can be used
a*	means that the a element can be repeated 0 or more times
a+	means that the a element can be repeated 1 or more times

The Attributes Tables in the sections below describe the XML attributes that can be used with the tags.

Configuration

This is the topmost scope level. A configuration must start with a <configuration> tag.

<configuration>
  [ <description> ] [ <typedef>* ] [{ <definition> | <feature> | <tunable> ]*
  [ <setting>* ] [ <action>* ] [ <constraint>* ]
  [{ <folder> | <folderRef> }]*

Table 7-2 Attributes for Configuration

Attribute	Description
name: string	Name of the configuration

Folder Declaration

A folder is used to scope variables, and to set up a hierarchy in the ChorusOS system configuration. A condition can be used on a folder to disable it (if the condition evaluates to false). Any element located in a disabled folder is also disabled.

<folder>
  [ <description> ] [ <typedef>* ] [ <definition> | <feature> | <tunable> ]*
  [ <setting>* ] [ <action>* ] [ <constraint>* ]
  [ <folder> | <folderRef> ]*

Table 7-3 Attributes for Folder

Attribute	Description
name: string	Name of the folder
visible: 'yes' or 'no'	Default: 'yes'. Specifies if a configuration tool should show this folder or not. If the folder is not visible, all of its content is hidden as well.

Folder Link

A folder link is used to include another file. This is used to split the configuration into several files.

<folderRef>  

Table 7-4 Attributes for Folder Link

Attribute	Description
href: URL	Path of the file to include
visible: 'yes' or 'no'	Default: 'yes'. Specifies if the content of the included file must be visible in a configuration tool.

Description

This is used to bind a description to an element. The description text can be displayed in a configuration tool.

<description> text

Definition

This is used to declare a variable. The declaration is fully typed, and can be conditioned by a <condition> boolean expression. If the condition evaluates to 'false', the variable is not declared.

<definition>
  [ <description> ] [ <condition> ] type_content [{ expression | <value>* }]

Table 7-5 Attributes of Definition

Attribute	Description
name: string	Name of the variable to declare
configurable: 'yes' or 'no'	Default: 'no'. Specifies if the value of this variable can be changed with a configuration tool.
visible: 'yes' or 'no'	Default: 'no'. Specifies if this variable declaration must be visible in a configuration tool.
global: 'yes' or 'no'	Default: 'yes'. Specifies if this variable is scoped into the folder where it is declared.

Feature

This is used to declare a ChorusOS system feature. A feature declaration has the same semantics as a variable declaration, but it is always visible, configurable, and global.

<feature>
  [ <description> ] [ <condition> ] type_content [ <const> | boolean_values ]

Table 7-6 Attributes for Feature

Attribute	Description
name: string	Name of variable to declare

Tunable

This is used to declare a ChorusOS system tunable. A tunable declaration has the same semantics as a variable declaration, but it is always visible, configurable, and global.

<tunable>
  [ <description> ] [ <condition> ] type_content [ <const> | boolean_const ]

Table 7-7 Attributes for Tunable

Attribute	Description
name: string	Name of the variable to declare

Boolean Constants

This defines the 'true' and 'false' boolean constants.

boolean_const
  { <true> | <false> }

Type Content

This is the set of types available for variable declarations.

type_content
  { <bool> | <int> | <string> | <enum> | <struct> | <list> | <type> }

Integers

This is used to declare a variable as an integer. An integer is assigned a value of 64 bits.

<int>

Table 7-8 Attribute for Integer

Attribute	Description
min: integer value	Minimum value authorized for this integer.
max: integer value	Maximum value authorized for this integer.

String

This is used to declare a variable as a string.

<string>

Enumerations

This is used to declare an enumerated value. The <const> sub-elements define all the possible values of the enumeration.

<enum>
  <const>+

Structures

This is used to declare a structured variable.

<struct>
  <field>+

Structure Fields

This is used to describe the characteristics of a structure field.

<field>
  [ <description> ] type_content expression

Table 7-9 Attributes of Field

Attribute	Description
name: string	Name of the field
optional: 'yes' or 'no'	Default 'no'. Specifies if this field can be omitted when setting the initial value of a variable in its declaration.
ref-only: 'yes' or 'no'	Default 'no'. Specifies if this field contains only a references to another variable.

Lists

Used to declare a list variable. The type_content sub-element is used to type the element of the list.

Table 7-10 Attributes of List

Attribute	Description
ref-only: 'yes' or 'no'	Specifies if this list only contains references to other variables.

Boolean Expressions

Boolean expressions are written in a post-fixed notation. They are used wherever a boolean result is expected.

boolean_expression
  { boolean_const | <and> | <or> | <not> | <equal> | <notequal> |
    <ifdef> | <imply> }

Expressions

Generic expressions are an extension of boolean expressions which can produce variable reference, string, or enumeration constants.

expression
  { boolean_expression | <ref> | <vstring> | <const> }

Variable Reference

This is used to reference another variable by its name. The variable must be declared and accessible in the scope of this reference.

<ref>

Table 7-11 Attributes of Variable Reference

Attribute	Description
name:string	Name of the referenced variable.

Test of Variable Existence

This test returns true if the specified variable exists or has been declared.

<ifdef>

Table 7-12 Attribute of Variable Existence

Attribute	Description
name: string	Name of the referenced variable.

Variable value

This allows you to get the current value of a variable. The specified variable must have been declared previously.

<var>

Table 7-13 Attributes of Variable Value

Attribute	Description
name: string	Name of the variable.

Conditions

A condition is used to validate or invalidate an element.

<condition>
  boolean_expression

Typedef

This declares a new type. A type definition is global in the configuration, and can be used in a 'type' reference.

<typedef>
  [ <description> ] type_content

Type

This is used to reference a type definition.

<type>

Table 7-14 Attributes of Type

Attribute	Description
name: string	Name of the referenced type. This type must have been declared in a typeDef.
ref-only: 'yes' or 'no'	Specifies if this type denotes a reference.

Settings

This is the assignment of a variable . The named variable is assigned with the given value. The variable must already have been declared before, and the value must have a correct type.

<setting>
  [ <description> ] [ <condition> ] type_content { expression | <value>* }

Table 7-15 Attribute of Setting

Attribute	Description
name: string	Name of variable

Constraints

A constraint is a boolean expression used to ensure the integrity of the configuration. If a constraint has a false value, the configuration tool considers the configuration to be invalid, and not to be used to generate a ChorusOS system image.

<constraint>
  [ <description> ] boolean_expression

Table 7-16 Attribute of Constraint

Attribute	Description
name: string	Name of the constraint.

Actions

An action takes a parameter which specifies the precise effect that will be performed by a configuration tool.

<action>
  [ <description> ] [ <condition> ] <application> {<definition>|expression}

Table 7-17 Attribute of Action

Attribute	Description
name: string	Name of the action

Action Application

This determines which action of the configuration tool will be applied. Currently, only the configure application exists and uses a variable typed as Configure structure as a parameter.

<application>
   text