Adding EPL version of configurationengine.
User guide for HCR Plugin usage in ConE
=======================================
Introduction
------------
This page describes how to use ConE HCR plug-in (for Hardware configuration repository).
The plug-in defines the HCRML Implementation Markup Language, whose purpose is to provide
the means for creating bindings between ConfML settings and Hardware Configuration Repository
keys, and generating hcr.dat and C++ header files based on these bindings.
XML namespace and file extension
--------------------------------
- Namespace: ``http://www.symbianfoundation.org/xml/hcrml/1``
- File extension: ``hcrml``
HCRML elements
--------------
The HCRML model is drawn out as a UML model in below picture.
.. image:: hcrml_elements.jpg
category
^^^^^^^^
The category represents the same concept as a category in the HCR specification, which must have a name and UID.
The category element can exist directly under the HCRML root element or an output element.
**Attributes**
* *name* - C++ variable name for the category UID in the generated header file
* *uid* - UID of the category, must be unique in the repository
**Example**
.. code-block:: xml
<category name="KCatGPIO" uid="0x10001234">
setting
^^^^^^^
The setting is a sub element of category, it can only exist inside a category. The setting can have the following
attributes:
**Attributes**
* *name* - C++ variable name for the setting UID in the generated header file
* *id* - UID of the setting, must be unique under a certain category
* *type* - Type of the setting (can be one of setting value types, see next section)
* *comment* - Single-line comment for the setting (visible in the generated header file)
**Setting value type definitions**
The HCRML value type definitions are derived from repository definitions. So the value type is the
same in HCRML, where the prefix EType has been removed and the entry is in lower case.
============== ==============
HCRML type HCR type
============== ==============
int32 ETypeInt32
int16 ETypeInt16
int8 ETypeInt8
bool ETypeBool
uint32 ETypeUInt32
uint16 ETypeUInt16
uint8 ETypeUInt8
linaddr ETypeLinAddr
bindata ETypeBinData
text8 ETypeText8
arrayint32 ETypeArrayInt32
arrayuint32 ETypeArrayUInt32
int64 ETypeInt64
uint64 ETypeUInt64
============== ==============
Note:
Data for the type ``text8`` is encoded in UTF-8. This means that pure ASCII text will work
correctly without any further processing, and if any characters outside the ASCII range
are expected to be in the text, the C++ implementation will need to take the encoding into
account.
**Supported ConfML setting types for HCRML types**
+------------------+------------------------------------------------------------------+
| HCRML type | ConfML setting type |
+==================+==================================================================+
| int8, int16, | int |
| int32, int64, | |
| uint8, uint16, | |
| uint32, uint64, | |
| linaddr | |
+------------------+------------------------------------------------------------------+
| bool | boolean, int |
+------------------+------------------------------------------------------------------+
| arrayint32, | Sequence with an int sub-setting |
| arrayuint32 | |
+------------------+------------------------------------------------------------------+
| text8 | string |
+------------------+------------------------------------------------------------------+
| bindata | string with a hexadecimal value, whitespace ignored |
| | (e.g. ``ABCDEF 1234 5678``) |
+------------------+------------------------------------------------------------------+
**Examples**
.. code-block:: xml
<setting ref="hcrexample.DebounceInterval" name="KElmGPIO_DebounceInterval" type="int32" id="0"/>
<setting ref="hcrexample.GPIO_1" name="KElmGPIO_1" type="int32" id="1" comment="Pin1"/>
<setting ref="hcrexample.GPIO_2" name="KElmGPIO_2" type="int32" id="2" comment="Pin2"/>
flags
^^^^^
Flags element is a subelement of setting that can be used to define bit flags to a setting.
**Attributes**
Each flag attribute can have values 0,1, default value is 0.
* *uninitialised*
* *modifiable*
* *persistent*
**Examples**
.. code-block:: xml
<flags uninitialized="0"/>
<flags modifiable="1" persistent="1"/>
output
^^^^^^
Output element is a subelement of the root HCRML element used define output file generation. The output element
should include a set of category and setting definitions that are included in the output file. The output section can
also include other HCRML files to include category/setting definitions to it.
If the included HCRML files contain output sections of their own, the generation is supposed the generate
only the topmost output element. So any included output element is simply ignored.
**Attributes**
* *file* - The output filename to be generated)
* *type* - The output file type, which can be one of [header|hcr]
* *version* - For hcr.dat, the HCR version number
* *readonly* - For hcr.dat, the read-only bit
**Examples**
.. code-block:: xml
<output file="test.h" type="header">
</output>
<output file="HCR.DAT" type="hcr" version="1">
</output>
include
^^^^^^^
Include element can be used to include content of other HCRML files. The purpose is mainly to allow
inclusion of categories and settings inside the output section. It allows wildcards to enable inclusion of
multiple HCRML files with single line, or the inclusion of all existing HCRML files.
**Attributes**
* *ref* - The pattern for including files
**Examples**
.. code-block:: xml
<include ref="foo.hcrml">
<include ref="bar.hcrml">
<include ref="my*.hcrml">
Creating an HCRML configuration file
------------------------------------
The HCRML format is designed for two purposes. To allow definition of components specific binding
between confml settings and Hardware configuration repository keys and to create/generate a C++ type
header file from HCR key definition file. Secondly to allow creation/generation of Hardware
configuration repository output file from multiple developer/component specific HCRML files.
The normal lifecycle of these implementation files is described in below.
1. Create/define the components configuration interface with confml
2. Create/define the needed hcr keys and the binding between confml features.
3. Generate the C++ header for the component from the configuration project
* e.g. ``cone generate`` (in the conf folder)
4. Export/merge the component configuration as part of global configuration
* e.g. ``cone merge -r . -p /epoc32/rom/config_project/hcr`` (in the conf folder)
.. image:: hcrml_developer_project.png
5. Define hcrml for hcr.dat generation. (Should be eventually in the same hcr layer inside the configuration project)
6. Generate the HCR.DAT
* e.g. ``cone generate -p /epoc32/rom/config_project/hcr``
.. image:: hcrml_global_project.png
Examples
--------
**HCRML file example**
.. code-block:: xml
<?xml version="1.0" encoding="UTF-8"?>
<hcr xmlns="http://www.symbianfoundation.org/xml/hcrml/1">
<output file="example.h" type="header">
<category name="KCatGPIO" uid="0x10001234">
<setting ref="hcrexample.DebounceInterval" name="KElmGPIO_DebounceInterval" type="int32" id="0"/>
<setting ref="hcrexample.GPIO_1" name="KElmGPIO_1" type="int32" id="1" comment="Pin1"/>
<setting ref="hcrexample.GPIO_2" name="KElmGPIO_2" type="int32" id="2" comment="Pin2"/>
</category>
</output>
</hcr>
**Explanation**
The above HCRML file defines three settings's under category KCatGPIO, which has the UID 0x10001234. Each
setting must have a unique ID inside the category. And each setting must define ref that points to a confml
setting. The data value of that particular key is fetched from that confml reference. The name element
in the category and settings can be used to generate the C header file from the HCRML.
A output element encapsulates the setting definitions in this file. It is not necessary, but it enables
that example.h header file can be generated from this component specific HCRML file.
**HCR repository file example**
.. code-block:: xml
<?xml version="1.0" encoding="UTF-8"?>
<hcr xmlns="http://www.symbianfoundation.org/xml/hcrml/1">
<output file="HCR.DAT" type="hcr" version="1" readOnly="1">
<include ref="*.hcrml">
</output>
</hcr>
**Explanation**
The above HCRML entry would define a HCR binary output file HCR.DAT with version 1 and readonly bit true.
The file generation will try to include all .hcrml ending files from the configuration project.
The include statement will just look for any matching file and include its content inside this file. If the
included hcrml files include an output section, they are simple ingored and only the topmost output
file will be generated.
The output file section will in the end contain all categories and keys of all HCRML files.
These files would normally be the files which are exported to the configuration project from several
component configurations.
Downloadable example
--------------------
Download: :download:`hcrml_example.zip`
This example contains a mock developer project like shown earlier. It has
a ``conf/`` directory containing the ConfML and HCRML files, and (empty) ``inc/``,
``src/`` and ``group/`` directories. The important part is the ``conf/`` directory, which
contains the following files:
- ``confml/hcr_component1.confml`` - ConfML interface for the HCR settings
- ``implml/component1.hcrml`` - HCRML file defining the binding between the ConfML settings and the HCR settings
- ``implml/hcr_dat.hcrml`` - HCRML file for generating ``hcr.dat``
- ``implml/hcr_keys.hcrml`` - HCRML file for generating ``hcr_keys.h``
- ``root.confml`` - Needed for generation to work; contains a link to ``confml/hcr_component1.confml``
To generate, cd to ``component1/conf/`` and run::
cone generate
This will generate an ``output/`` directory with the files ``hcr.dat`` and ``hcr_keys.h``.
Linking between ConfML/HCRML/output
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Here the linking between ConfML/HCRML/output is shown using the binary data
setting. Irrelevant parts of the files are omitted for clarity.
**ConfML:**
.. code-block:: xml
<feature ref="HcrComponent1" name="HCR test component 1">
...
<setting ref="BinDataSetting" name="Binary data setting" type="string"/>
...
</feature>
...
<data>
<HcrComponent1>
...
<BinDataSetting>00112233 DEADBEEF CAFE 50</BinDataSetting>
...
</HcrComponent1>
</data>
**HCRML:**
.. code-block:: xml
<category name="KHcrComponent1" uid="0x00000001">
...
<setting ref="HcrComponent1.BinDataSetting" name="KBinDataSetting" type="bindata" id="5" comment="Binary data setting"/>
...
</category>
**Output - hcr.dat:**
.. image:: hcr_dat.png
**Output - hcr_keys.h:**
.. code-block:: c++
#ifndef HCR_KEYS_H
#define HCR_KEYS_H
#include <hcr.h>
const HCR::TCategoryUid KHcrComponent1 = 0x00000001;
...
// Binary data setting
const HCR::TElementId KBinDataSetting = 0x00000005;
#endif
XSD
---
Download: :download:`hcrml.xsd </xsd/hcrml.xsd>`
FAQ
---
This will be updated based on the questions.