|
1 User guide for HCR Plugin usage in ConE |
|
2 ======================================= |
|
3 |
|
4 Introduction |
|
5 ------------ |
|
6 This page describes how to use ConE HCR plug-in (for Hardware configuration repository). |
|
7 The plug-in defines the HCRML Implementation Markup Language, whose purpose is to provide |
|
8 the means for creating bindings between ConfML settings and Hardware Configuration Repository |
|
9 keys, and generating hcr.dat and C++ header files based on these bindings. |
|
10 |
|
11 XML namespace and file extension |
|
12 -------------------------------- |
|
13 |
|
14 - Namespace: ``http://www.symbianfoundation.org/xml/hcrml/1`` |
|
15 - File extension: ``hcrml`` |
|
16 |
|
17 HCRML elements |
|
18 -------------- |
|
19 |
|
20 The HCRML model is drawn out as a UML model in below picture. |
|
21 |
|
22 .. image:: hcrml_elements.jpg |
|
23 |
|
24 category |
|
25 ^^^^^^^^ |
|
26 |
|
27 The category represents the same concept as a category in the HCR specification, which must have a name and UID. |
|
28 The category element can exist directly under the HCRML root element or an output element. |
|
29 |
|
30 **Attributes** |
|
31 |
|
32 * *name* - C++ variable name for the category UID in the generated header file |
|
33 * *uid* - UID of the category, must be unique in the repository |
|
34 |
|
35 **Example** |
|
36 |
|
37 .. code-block:: xml |
|
38 |
|
39 <category name="KCatGPIO" uid="0x10001234"> |
|
40 |
|
41 |
|
42 setting |
|
43 ^^^^^^^ |
|
44 |
|
45 The setting is a sub element of category, it can only exist inside a category. The setting can have the following |
|
46 attributes: |
|
47 |
|
48 **Attributes** |
|
49 |
|
50 * *name* - C++ variable name for the setting UID in the generated header file |
|
51 * *id* - UID of the setting, must be unique under a certain category |
|
52 * *type* - Type of the setting (can be one of setting value types, see next section) |
|
53 * *comment* - Single-line comment for the setting (visible in the generated header file) |
|
54 |
|
55 |
|
56 **Setting value type definitions** |
|
57 |
|
58 The HCRML value type definitions are derived from repository definitions. So the value type is the |
|
59 same in HCRML, where the prefix EType has been removed and the entry is in lower case. |
|
60 |
|
61 |
|
62 ============== ============== |
|
63 HCRML type HCR type |
|
64 ============== ============== |
|
65 int32 ETypeInt32 |
|
66 int16 ETypeInt16 |
|
67 int8 ETypeInt8 |
|
68 bool ETypeBool |
|
69 uint32 ETypeUInt32 |
|
70 uint16 ETypeUInt16 |
|
71 uint8 ETypeUInt8 |
|
72 linaddr ETypeLinAddr |
|
73 bindata ETypeBinData |
|
74 text8 ETypeText8 |
|
75 arrayint32 ETypeArrayInt32 |
|
76 arrayuint32 ETypeArrayUInt32 |
|
77 int64 ETypeInt64 |
|
78 uint64 ETypeUInt64 |
|
79 ============== ============== |
|
80 |
|
81 Note: |
|
82 Data for the type ``text8`` is encoded in UTF-8. This means that pure ASCII text will work |
|
83 correctly without any further processing, and if any characters outside the ASCII range |
|
84 are expected to be in the text, the C++ implementation will need to take the encoding into |
|
85 account. |
|
86 |
|
87 **Supported ConfML setting types for HCRML types** |
|
88 |
|
89 +------------------+------------------------------------------------------------------+ |
|
90 | HCRML type | ConfML setting type | |
|
91 +==================+==================================================================+ |
|
92 | int8, int16, | int | |
|
93 | int32, int64, | | |
|
94 | uint8, uint16, | | |
|
95 | uint32, uint64, | | |
|
96 | linaddr | | |
|
97 +------------------+------------------------------------------------------------------+ |
|
98 | bool | boolean, int | |
|
99 +------------------+------------------------------------------------------------------+ |
|
100 | arrayint32, | Sequence with an int sub-setting | |
|
101 | arrayuint32 | | |
|
102 +------------------+------------------------------------------------------------------+ |
|
103 | text8 | string | |
|
104 +------------------+------------------------------------------------------------------+ |
|
105 | bindata | string with a hexadecimal value, whitespace ignored | |
|
106 | | (e.g. ``ABCDEF 1234 5678``) | |
|
107 +------------------+------------------------------------------------------------------+ |
|
108 |
|
109 **Examples** |
|
110 |
|
111 .. code-block:: xml |
|
112 |
|
113 <setting ref="hcrexample.DebounceInterval" name="KElmGPIO_DebounceInterval" type="int32" id="0"/> |
|
114 <setting ref="hcrexample.GPIO_1" name="KElmGPIO_1" type="int32" id="1" comment="Pin1"/> |
|
115 <setting ref="hcrexample.GPIO_2" name="KElmGPIO_2" type="int32" id="2" comment="Pin2"/> |
|
116 |
|
117 flags |
|
118 ^^^^^ |
|
119 |
|
120 Flags element is a subelement of setting that can be used to define bit flags to a setting. |
|
121 |
|
122 **Attributes** |
|
123 |
|
124 Each flag attribute can have values 0,1, default value is 0. |
|
125 |
|
126 * *uninitialised* |
|
127 * *modifiable* |
|
128 * *persistent* |
|
129 |
|
130 |
|
131 **Examples** |
|
132 |
|
133 .. code-block:: xml |
|
134 |
|
135 <flags uninitialized="0"/> |
|
136 <flags modifiable="1" persistent="1"/> |
|
137 |
|
138 output |
|
139 ^^^^^^ |
|
140 |
|
141 Output element is a subelement of the root HCRML element used define output file generation. The output element |
|
142 should include a set of category and setting definitions that are included in the output file. The output section can |
|
143 also include other HCRML files to include category/setting definitions to it. |
|
144 |
|
145 If the included HCRML files contain output sections of their own, the generation is supposed the generate |
|
146 only the topmost output element. So any included output element is simply ignored. |
|
147 |
|
148 **Attributes** |
|
149 |
|
150 * *file* - The output filename to be generated) |
|
151 * *type* - The output file type, which can be one of [header|hcr] |
|
152 * *version* - For hcr.dat, the HCR version number |
|
153 * *readonly* - For hcr.dat, the read-only bit |
|
154 |
|
155 |
|
156 **Examples** |
|
157 |
|
158 .. code-block:: xml |
|
159 |
|
160 <output file="test.h" type="header"> |
|
161 </output> |
|
162 <output file="HCR.DAT" type="hcr" version="1"> |
|
163 </output> |
|
164 |
|
165 include |
|
166 ^^^^^^^ |
|
167 Include element can be used to include content of other HCRML files. The purpose is mainly to allow |
|
168 inclusion of categories and settings inside the output section. It allows wildcards to enable inclusion of |
|
169 multiple HCRML files with single line, or the inclusion of all existing HCRML files. |
|
170 |
|
171 **Attributes** |
|
172 |
|
173 * *ref* - The pattern for including files |
|
174 |
|
175 **Examples** |
|
176 |
|
177 .. code-block:: xml |
|
178 |
|
179 <include ref="foo.hcrml"> |
|
180 <include ref="bar.hcrml"> |
|
181 <include ref="my*.hcrml"> |
|
182 |
|
183 Creating an HCRML configuration file |
|
184 ------------------------------------ |
|
185 |
|
186 The HCRML format is designed for two purposes. To allow definition of components specific binding |
|
187 between confml settings and Hardware configuration repository keys and to create/generate a C++ type |
|
188 header file from HCR key definition file. Secondly to allow creation/generation of Hardware |
|
189 configuration repository output file from multiple developer/component specific HCRML files. |
|
190 |
|
191 The normal lifecycle of these implementation files is described in below. |
|
192 |
|
193 1. Create/define the components configuration interface with confml |
|
194 2. Create/define the needed hcr keys and the binding between confml features. |
|
195 3. Generate the C++ header for the component from the configuration project |
|
196 |
|
197 * e.g. ``cone generate`` (in the conf folder) |
|
198 |
|
199 4. Export/merge the component configuration as part of global configuration |
|
200 |
|
201 * e.g. ``cone merge -r . -p /epoc32/rom/config_project/hcr`` (in the conf folder) |
|
202 |
|
203 .. image:: hcrml_developer_project.png |
|
204 |
|
205 5. Define hcrml for hcr.dat generation. (Should be eventually in the same hcr layer inside the configuration project) |
|
206 6. Generate the HCR.DAT |
|
207 |
|
208 * e.g. ``cone generate -p /epoc32/rom/config_project/hcr`` |
|
209 |
|
210 .. image:: hcrml_global_project.png |
|
211 |
|
212 Examples |
|
213 -------- |
|
214 |
|
215 **HCRML file example** |
|
216 |
|
217 .. code-block:: xml |
|
218 |
|
219 <?xml version="1.0" encoding="UTF-8"?> |
|
220 <hcr xmlns="http://www.symbianfoundation.org/xml/hcrml/1"> |
|
221 <output file="example.h" type="header"> |
|
222 <category name="KCatGPIO" uid="0x10001234"> |
|
223 <setting ref="hcrexample.DebounceInterval" name="KElmGPIO_DebounceInterval" type="int32" id="0"/> |
|
224 <setting ref="hcrexample.GPIO_1" name="KElmGPIO_1" type="int32" id="1" comment="Pin1"/> |
|
225 <setting ref="hcrexample.GPIO_2" name="KElmGPIO_2" type="int32" id="2" comment="Pin2"/> |
|
226 </category> |
|
227 </output> |
|
228 </hcr> |
|
229 |
|
230 **Explanation** |
|
231 |
|
232 The above HCRML file defines three settings's under category KCatGPIO, which has the UID 0x10001234. Each |
|
233 setting must have a unique ID inside the category. And each setting must define ref that points to a confml |
|
234 setting. The data value of that particular key is fetched from that confml reference. The name element |
|
235 in the category and settings can be used to generate the C header file from the HCRML. |
|
236 |
|
237 A output element encapsulates the setting definitions in this file. It is not necessary, but it enables |
|
238 that example.h header file can be generated from this component specific HCRML file. |
|
239 |
|
240 **HCR repository file example** |
|
241 |
|
242 .. code-block:: xml |
|
243 |
|
244 <?xml version="1.0" encoding="UTF-8"?> |
|
245 <hcr xmlns="http://www.symbianfoundation.org/xml/hcrml/1"> |
|
246 <output file="HCR.DAT" type="hcr" version="1" readOnly="1"> |
|
247 <include ref="*.hcrml"> |
|
248 </output> |
|
249 </hcr> |
|
250 |
|
251 **Explanation** |
|
252 |
|
253 The above HCRML entry would define a HCR binary output file HCR.DAT with version 1 and readonly bit true. |
|
254 The file generation will try to include all .hcrml ending files from the configuration project. |
|
255 The include statement will just look for any matching file and include its content inside this file. If the |
|
256 included hcrml files include an output section, they are simple ingored and only the topmost output |
|
257 file will be generated. |
|
258 |
|
259 The output file section will in the end contain all categories and keys of all HCRML files. |
|
260 These files would normally be the files which are exported to the configuration project from several |
|
261 component configurations. |
|
262 |
|
263 Downloadable example |
|
264 -------------------- |
|
265 |
|
266 Download: :download:`hcrml_example.zip` |
|
267 |
|
268 This example contains a mock developer project like shown earlier. It has |
|
269 a ``conf/`` directory containing the ConfML and HCRML files, and (empty) ``inc/``, |
|
270 ``src/`` and ``group/`` directories. The important part is the ``conf/`` directory, which |
|
271 contains the following files: |
|
272 |
|
273 - ``confml/hcr_component1.confml`` - ConfML interface for the HCR settings |
|
274 - ``implml/component1.hcrml`` - HCRML file defining the binding between the ConfML settings and the HCR settings |
|
275 - ``implml/hcr_dat.hcrml`` - HCRML file for generating ``hcr.dat`` |
|
276 - ``implml/hcr_keys.hcrml`` - HCRML file for generating ``hcr_keys.h`` |
|
277 - ``root.confml`` - Needed for generation to work; contains a link to ``confml/hcr_component1.confml`` |
|
278 |
|
279 To generate, cd to ``component1/conf/`` and run:: |
|
280 |
|
281 cone generate |
|
282 |
|
283 This will generate an ``output/`` directory with the files ``hcr.dat`` and ``hcr_keys.h``. |
|
284 |
|
285 Linking between ConfML/HCRML/output |
|
286 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
|
287 |
|
288 Here the linking between ConfML/HCRML/output is shown using the binary data |
|
289 setting. Irrelevant parts of the files are omitted for clarity. |
|
290 |
|
291 **ConfML:** |
|
292 |
|
293 .. code-block:: xml |
|
294 |
|
295 <feature ref="HcrComponent1" name="HCR test component 1"> |
|
296 ... |
|
297 <setting ref="BinDataSetting" name="Binary data setting" type="string"/> |
|
298 ... |
|
299 </feature> |
|
300 ... |
|
301 <data> |
|
302 <HcrComponent1> |
|
303 ... |
|
304 <BinDataSetting>00112233 DEADBEEF CAFE 50</BinDataSetting> |
|
305 ... |
|
306 </HcrComponent1> |
|
307 </data> |
|
308 |
|
309 **HCRML:** |
|
310 |
|
311 .. code-block:: xml |
|
312 |
|
313 <category name="KHcrComponent1" uid="0x00000001"> |
|
314 ... |
|
315 <setting ref="HcrComponent1.BinDataSetting" name="KBinDataSetting" type="bindata" id="5" comment="Binary data setting"/> |
|
316 ... |
|
317 </category> |
|
318 |
|
319 **Output - hcr.dat:** |
|
320 |
|
321 .. image:: hcr_dat.png |
|
322 |
|
323 |
|
324 **Output - hcr_keys.h:** |
|
325 |
|
326 .. code-block:: c++ |
|
327 |
|
328 #ifndef HCR_KEYS_H |
|
329 #define HCR_KEYS_H |
|
330 |
|
331 #include <hcr.h> |
|
332 |
|
333 const HCR::TCategoryUid KHcrComponent1 = 0x00000001; |
|
334 |
|
335 ... |
|
336 |
|
337 // Binary data setting |
|
338 const HCR::TElementId KBinDataSetting = 0x00000005; |
|
339 |
|
340 #endif |
|
341 |
|
342 XSD |
|
343 --- |
|
344 |
|
345 Download: :download:`hcrml.xsd </xsd/hcrml.xsd>` |
|
346 |
|
347 FAQ |
|
348 --- |
|
349 |
|
350 This will be updated based on the questions. |
|
351 |