1# Configuration Management 2 3 4## HDF Configuration Overview 5 6HDF Configuration Source (HCS) is the source code that describes the HDF configuration in key-value pairs. It decouples the configuration code from driver code, simplifying configuration management. 7 8HDF Configuration Generator (HC-GEN) is a tool for converting an HDF configuration file into a file that can be read by the software. 9 10- In a low-performance system on a chip (SoC), this tool converts an HCS configuration file into the source code or macro definitions of the configuration tree. The driver can obtain the configuration by calling the C library code or macro-based APIs. 11 12- In a high-performance SoC, this tool converts an HCS configuration file into an HDF Configuration Binary (HCB) file. The driver can obtain the configuration by calling the configuration parsing APIs provided by the HDF. 13 14The figure below illustrates how an HCB file is used. 15 16 **Figure 1** Process of using an HCB file 17 18  19 20The HC-GEN converts the HCS into an HCB file. The HCS Parser module in the HDF rebuilds a configuration tree from the HCB file. The HDF driver obtains the configuration through the configuration read API provided by the HCS Parser. 21 22 23## Configuration Syntax 24 25The following describes the HCS syntax. 26 27 28### Keywords 29 30The table below describes the keywords used in the HCS syntax. 31 32 **Table 1** Keywords used in HCS syntax 33 34| Keyword| Description| Remarks| 35| -------- | -------- | -------- | 36| root | Sets the root node.| - | 37| include | References other HCS files.| - | 38| delete | Deletes a node or an attribute.| Applicable only to the configuration tree referenced by **include**.| 39| template | Defines a template node.| - | 40| match_attr | Marks the node attribute for matching.| During configuration parsing, the attribute value can be used to locate the corresponding node.| 41 42 43### Basic Structures 44 45The HCS has two structures: attribute and node. 46 47**Attribute** 48 49An attribute is the minimum, independent configuration unit. The syntax is as follows: 50 51 52``` 53 attribute_name = value; 54``` 55 56- **attribute_name** is a case-sensitive string of letters, digits, and underscores (_) and must start with a letter or underscore (_). 57 58- The **value** can be in any of the following formats: 59 60 - A binary, octal, decimal, or hexadecimal integer. For details, see the **Data Types** section. 61 - String quoted by double quotation marks (""). 62 - Node reference. 63 64- An attribute key-value pair must end with a semicolon (;) and belong to a node. 65 66**Node** 67 68A node is a set of attributes. The syntax is as follows: 69 70 71``` 72 node_name { 73 module = "sample"; 74 ... 75 } 76``` 77 78- **node_name** is a case-sensitive string of letters, digits, and underscores (_) and must start with a letter or underscore (_). 79 80- No semicolon (;) is required after the curly brace ({) or (}). 81 82- The keyword **root** is used to declare the root node of a configuration table. Each configuration table must start with the root node. 83 84- The root node must contain a **module** attribute. The value is a string indicating the module to which the configuration belongs. 85 86- The **match_attr** attribute can be added to a node. Its value is a globally unique string. During configuration parsing, the **match_attr** attribute can be used to quickly locate the node that contains the attribute. 87 88 89### Data Types 90 91Attributes automatically use built-in data types, including integer, string, array, and boolean. You do not need to explicitly specify the data type for the attribute values. 92 93**Integer** 94 95 An integer can be binary, octal, decimal, or hexadecimal. The minimum space is automatically allocated to the integer based on the actual data length. 96- Binary: prefixed with **0b**, for example, **0b1010**. 97 98- Octal: prefixed with **0**, for example, **0664**. 99 100- Decimal: signed or unsigned, without prefix, for example, **1024** or **+1024**. Negative integers can be read only via signed interfaces. 101 102- Hexadecimal: prefixed with **0x**, for example, **0xff00** and **0xFF**. 103 104**String** 105 106A string is enclosed in double quotation marks (""). 107 108**Array** 109 110An array can hold either integers or strings, but not a mixture of them. The mixed use of **uint32_t** and **uint64_t** in an integer array will cause typecasting to **uint64**. The following is an example of an integer array and a string array: 111 112 113``` 114attr_foo = [0x01, 0x02, 0x03, 0x04]; 115attr_bar = ["hello", "world"]; 116``` 117 118**Boolean** 119 120Boolean data type is a form of data with only two possible values: **true** and **false**. 121 122 123### Preprocessing 124 125**include** 126 127The keyword **include** is used to import other HCS files. The syntax is as follows: 128 129 130``` 131#include "foo.hcs" 132#include "../bar.hcs" 133``` 134 135- The file name must be enclosed in double quotation marks (""). If the file to be included is in a different directory with the target file, use a relative path. The included file must be a valid HCS file. 136 137- If multiple HCS files included contain the same nodes, the same nodes will be overridden and other nodes are listed in sequence. 138 139 140### Comments 141 142The following two comment formats are supported: 143 144- Single-line comment 145 146 147 ``` 148 // comment 149 ``` 150 151- Multi-line comment 152 153 154 ``` 155 /* 156 comment 157 */ 158 ``` 159 160 >  **NOTE**<br/> 161 > Multi-line comments cannot be nested. 162 163 164### Reference Modification 165 166You can reference the content of a node to modify the content of another node. The syntax is as follows: 167 168 169``` 170 node :& source_node 171``` 172 173In this statement, the content of **node** is referenced to modify the content of **source_node**. 174 175Example: 176 177``` 178root { 179 module = "sample"; 180 foo { 181 foo_ :& root.bar{ 182 attr = "foo"; 183 } 184 foo1 :& foo2 { 185 attr = 0x2; 186 } 187 foo2 { 188 attr = 0x1; 189 } 190 } 191 192 bar { 193 attr = "bar"; 194 } 195} 196``` 197 198The configuration tree generated is as follows: 199 200 201``` 202root { 203 module = "sample"; 204 foo { 205 foo2 { 206 attr = 0x2; 207 } 208 } 209 bar { 210 attr = "foo"; 211 } 212} 213``` 214 215In this example, the value of **bar.attr** is changed to **foo** by referencing **foo.foo_**, and the value of **foo.foo2.attr** is changed to **0x2** by referencing **foo.foo1**. The **foo.foo_** and **foo.foo1** nodes are used to modify the content of the target nodes, and do not exist in the configuration tree generated. 216 217- A node of the same level can be referenced simply using the node name. To reference a node of a different level, use the absolute path starting with **root**, and separate the node names using a period (.). **root** indicates the root node. For example, **root.foo.bar**. 218 219- If multiple modifications are made to the same attribute, only one modification takes effect and a warning will be displayed for you to confirm the result. 220 221 222### Node Replication 223 224You can replicate a node to define a node with similar content. The syntax is as follows: 225 226 227``` 228 node : source_node 229``` 230 231This statement replicates the attributes of the **source_node** node to define **node**. 232 233Example: 234 235 236``` 237root { 238 module = "sample"; 239 foo { 240 attr_0 = 0x0; 241 } 242 bar:foo { 243 attr_1 = 0x1; 244 } 245} 246``` 247 248The configuration tree generated is as follows: 249 250 251``` 252root { 253 module = "sample"; 254 foo { 255 attr_0 = 0x0; 256 } 257 bar { 258 attr_1 = 0x1; 259 attr_0 = 0x0; 260 } 261} 262``` 263 264In this example, the **bar** node contains **attr_0** and **attr_1** attributes, and the modification of the **attr_0** attribute in the **bar** node does not affect the **foo** node. 265 266You do not need to specify the path of the **foo** node if the **foo** node and the **bar** node are of the same level. Otherwise, specify the absolute path of **foo**. For details, see [Reference Modification](referencemodification). 267 268 269### Delete 270 271You can use the keyword **delete** to delete unnecessary nodes or attributes from the base configuration tree imported by using the **include** keyword. The following example includes the configuration in **sample2.hcs** to **sample1.hcs** and deletes the **attribute2** attribute and the **foo_2** node. 272 273Example: 274 275 276``` 277// sample2.hcs 278root { 279 attr_1 = 0x1; 280 attr_2 = 0x2; 281 foo_2 { 282 t = 0x1; 283 } 284} 285 286// sample1.hcs 287#include "sample2.hcs" 288root { 289 attr_2 = delete; 290 foo_2 : delete { 291 } 292} 293``` 294 295The configuration tree generated is as follows: 296 297 298``` 299root { 300 attr_1 = 0x1; 301} 302``` 303 304>  **NOTE**<br/> 305> The keyword **delete** cannot be used to delete nodes or attributes in the same HCS file. In an HCS file, you can directly delete unnecessary attributes. 306 307 308### Attribute Reference 309 310You can associate an attribute and a node so that the node can be quickly located when the attribute is read during configuration parsing. The syntax is as follows: 311 312 313``` 314 attribute = &node; 315``` 316 317In this statement, the value of **attribute** is a referenced to the node. During code parsing, you can quickly locate the node based on this **attribute**. 318 319Example: 320 321 322``` 323node1 { 324 attributes; 325} 326node2 { 327 attr_1 = &root.node1; 328} 329``` 330 331Or 332 333 334``` 335node2 { 336 node1 { 337 attributes; 338 } 339 attr_1 = &node1; 340} 341``` 342 343 344### Template 345 346The template is used to generate nodes with consistent syntax, thereby facilitating the traverse and management of nodes of the same type. 347 348If a node is defined using the keyword **template**, its child nodes inherit from the node configuration through the double colon operator (::). The child nodes can modify or add but cannot delete attributes in **template**. The attributes not defined in the child nodes will use the attributes defined in **template** as the default values. 349 350Example: 351 352 353``` 354root { 355 module = "sample"; 356 template foo { 357 attr_1 = 0x1; 358 attr_2 = 0x2; 359 } 360 361 bar :: foo { 362 } 363 364 bar_1 :: foo { 365 attr_1 = 0x2; 366 } 367} 368``` 369 370The configuration tree generated is as follows: 371 372 373``` 374root { 375 module = "sample"; 376 bar { 377 attr_1 = 0x1; 378 attr_2 = 0x2; 379 } 380 bar_1 { 381 attr_1 = 0x2; 382 attr_2 = 0x2; 383 } 384} 385``` 386 387In this example, the **bar** and **bar_1** nodes inherit from the **foo** node. The structure of the generated configuration tree is the same as that of the **foo** node, except that the attribute values are different. 388 389 390## **Configuration Generation** 391 392The HC-GEN tool checks the HCS configuration syntax and converts HCS source files into HCB files. 393 394 395### HC-GEN 396 397HC-GEN options: 398 399 400``` 401Usage: hc-gen [Options] [File] 402options: 403 -o <file> output file name, default same as input 404 -a hcb align with four bytes 405 -b output binary output, default enable 406 -t output config in C language source file style 407 -m output config in macro source file style 408 -i output binary hex dump in C language source file style 409 -p <prefix> prefix of generated symbol name 410 -d decompile hcb to hcs 411 -V show verbose info 412 -v show version 413 -h show this help message 414``` 415 416Generate a .c or .h configuration file. 417 418 419``` 420hc-gen -o [OutputCFileName] -t [SourceHcsFileName] 421``` 422 423Generate an HCB file. 424 425 426``` 427hc-gen -o [OutputHcbFileName] -b [SourceHcsFileName] 428``` 429 430Generate a macro definition file. 431 432 433``` 434hc-gen -o [OutputMacroFileName] -m [SourceHcsFileName] 435``` 436 437Decompile an HCB file to an HCS file. 438 439 440``` 441hc-gen -o [OutputHcsFileName] -d [SourceHcbFileName] 442``` 443
