1# Configuration Management 2 3 4## HDF Configuration Overview 5 6HDF Configuration Source (HCS) provides the source code that describes the HDF configuration in key-value pairs. It decouples the configuration code from driver code, thereby facilitating 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.| When parsing the configuration, the driver can use the attribute value as a parameter to call an API to locate the node that has this attribute. | 41 42 43### Basic Structures 44 45The HCS has two structures: attribute and node. 46 47Attribute 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 [Data Types](#data-types). 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 APIs with signed numbers. 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 118Boolean 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``` 177root { 178 module = "sample"; 179 foo { 180 foo_ :& root.bar{ 181 attr = "foo"; 182 } 183 foo1 :& foo2 { 184 attr = 0x2; 185 } 186 foo2 { 187 attr = 0x1; 188 } 189 } 190 191 bar { 192 attr = "bar"; 193 } 194} 195``` 196 197The configuration tree generated is as follows: 198 199 200``` 201root { 202 module = "sample"; 203 foo { 204 foo2 { 205 attr = 0x2; 206 } 207 } 208 bar { 209 attr = "foo"; 210 } 211} 212``` 213 214In 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. 215 216- 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**. 217 218- 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. 219 220 221### Node Replication 222 223You can replicate a node to define a node with similar content. The syntax is as follows: 224 225 226``` 227 node : source_node 228``` 229 230This statement replicates the attributes of the **source_node** node to define **node**. 231 232Example: 233 234``` 235root { 236 module = "sample"; 237 foo { 238 attr_0 = 0x0; 239 } 240 bar:foo { 241 attr_1 = 0x1; 242 } 243} 244``` 245 246The configuration tree generated is as follows: 247 248 249``` 250root { 251 module = "sample"; 252 foo { 253 attr_0 = 0x0; 254 } 255 bar { 256 attr_1 = 0x1; 257 attr_0 = 0x0; 258 } 259} 260``` 261 262In 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. 263 264You 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](#reference-modification). 265 266 267### Delete 268 269You 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. 270 271Example: 272 273``` 274// sample2.hcs 275root { 276 attr_1 = 0x1; 277 attr_2 = 0x2; 278 foo_2 { 279 t = 0x1; 280 } 281} 282 283// sample1.hcs 284#include "sample2.hcs" 285root { 286 attr_2 = delete; 287 foo_2 : delete { 288 } 289} 290``` 291 292The configuration tree generated is as follows: 293 294 295``` 296root { 297 attr_1 = 0x1; 298} 299``` 300 301>  **NOTE**<br/> 302> 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. 303 304 305### Attribute Reference 306 307You 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: 308 309 310``` 311 attribute = &node; 312``` 313 314In 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**. 315 316Example: 317 318``` 319node1 { 320 attributes; 321} 322node2 { 323 attr_1 = &root.node1; 324} 325``` 326 327Or 328 329 330``` 331node2 { 332 node1 { 333 attributes; 334 } 335 attr_1 = &node1; 336} 337``` 338 339 340### Template 341 342The template is used to generate nodes with consistent syntax, thereby facilitating the traverse and management of nodes of the same type. 343 344If 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. 345 346Example: 347 348``` 349root { 350 module = "sample"; 351 template foo { 352 attr_1 = 0x1; 353 attr_2 = 0x2; 354 } 355 356 bar :: foo { 357 } 358 359 bar_1 :: foo { 360 attr_1 = 0x2; 361 } 362} 363``` 364 365The configuration tree generated is as follows: 366 367 368``` 369root { 370 module = "sample"; 371 bar { 372 attr_1 = 0x1; 373 attr_2 = 0x2; 374 } 375 bar_1 { 376 attr_1 = 0x2; 377 attr_2 = 0x2; 378 } 379} 380``` 381 382In 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. 383 384 385## Configuration Generation 386 387The HC-GEN tool checks the HCS configuration syntax and converts HCS source files into HCB files. 388 389 390### HC-GEN 391 392HC-GEN options: 393 394 395``` 396Usage: hc-gen [Options] [File] 397options: 398 -o <file> output file name, default same as input 399 -a hcb align with four bytes 400 -b output binary output, default enable 401 -t output config in C language source file style 402 -m output config in macro source file style 403 -i output binary hex dump in C language source file style 404 -p <prefix> prefix of generated symbol name 405 -d decompile hcb to hcs 406 -V show verbose info 407 -v show version 408 -h show this help message 409``` 410 411Generate a .c or .h configuration file. 412 413 414``` 415hc-gen -o [OutputCFileName] -t [SourceHcsFileName] 416``` 417 418Generate an HCB file. 419 420 421``` 422hc-gen -o [OutputHcbFileName] -b [SourceHcsFileName] 423``` 424 425Generate a macro definition file. 426 427 428``` 429hc-gen -o [OutputMacroFileName] -m [SourceHcsFileName] 430``` 431 432Decompile an HCB file to an HCS file. 433 434 435``` 436hc-gen -o [OutputHcsFileName] -d [SourceHcbFileName] 437``` 438
