Appendix A ECML Syntax

This appendix provides an overview of the XML-based ECML syntax, used in the building and configuration processes of the ChorusOS operating system. 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 5.0 Board Support Package Developer's Guide also explains how to modify the target XML configuration files when adapting ChorusOS to a new target board.

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 A-1 Semantics of Grammar in XML Files

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

For a detailed examination of an ECML file, with comments and explanations, see "The target.xml File Structure" in ChorusOS 5.0 Board Support Package Developer's Guide.

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 A-2 Configuration Attributes

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 A-3 Folder Attributes

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 A-4 Folder Link Attributes

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.
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 A-5 Definition Attributes

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 A-6 Feature Attributes

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 A-7 Tunable Attributes

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 A-8 Integer Attributes

Attribute	Description
min: integer value	Minimum value allowed for this integer.
max: integer value	Maximum value allowed 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 A-9 Field Attributes

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 references to another variable.
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 A-10 List Attributes

Attributes	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 that 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 A-11 Variable Reference Attributes

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 A-12 Variable Existence Attribute

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 A-13 Variable Value Attributes

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 A-14 Type Attributes

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, and the value must have a correct type.

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

Table A-15 Setting Attribute

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 A-16 Constraint Attribute

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 A-17 Action Attribute

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, Configure, as a parameter.

<application>
   text