diff -r 000000000000 -r 2e8eeb919028 configurationengine/doc/plugins/hcrml-plugin/hcrml-plugin.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/configurationengine/doc/plugins/hcrml-plugin/hcrml-plugin.rst	Thu Mar 11 17:04:37 2010 +0200
@@ -0,0 +1,351 @@
+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.
+