1 /* 2 * Copyright (c) 2020-2021 Huawei Device Co., Ltd. 3 * 4 * HDF is dual licensed: you can use it either under the terms of 5 * the GPL, or the BSD license, at your option. 6 * See the LICENSE file in the root of this repository for complete details. 7 */ 8 9 /** 10 * @addtogroup DriverConfig 11 * @{ 12 * 13 * @brief Defines APIs for HDF driver developers to read driver configuration information. 14 * 15 * During version compilation of the device resource source file defined by developers, the compilation tool 16 * (for example, the compilation tool of the HCS file is hc-gen) generates bytecodes. When the HDF starts, 17 * it transfers the bytecode memory to the <b>DriverConfig</b> module. The <b>DriverConfig</b> module converts 18 * the bytecodes into a configuration tree and provides APIs for developers to query the tree. 19 * 20 * @since 1.0 21 * @version 1.0 22 */ 23 24 /** 25 * @file device_resource_if.h 26 * 27 * @brief Declares the APIs for querying the configuration tree. 28 * 29 * @since 1.0 30 * @version 1.0 31 */ 32 33 #ifndef DEVICE_RESOURCE_IF_H 34 #define DEVICE_RESOURCE_IF_H 35 36 #include "hdf_base.h" 37 38 #ifdef __cplusplus 39 #if __cplusplus 40 extern "C" { 41 #endif 42 #endif /* __cplusplus */ 43 44 /** 45 * @brief Enumerates configuration file types. 46 */ 47 typedef enum { 48 HDF_CONFIG_SOURCE = 0, /**< HDF configuration file */ 49 INVALID, /**< Invalid configuration file type */ 50 } DeviceResourceType; 51 52 /** 53 * @brief Defines the attributes of a tree node in the configuration tree. 54 * 55 * The tree node attributes are saved in a linked list. The information about each node in the linked list contains 56 * the attribute name, attribute value, and pointer that points to the next attribute. 57 */ 58 struct DeviceResourceAttr { 59 const char *name; /**< Pointer to the attribute name */ 60 const char *value; /**< Pointer to the attribute value */ 61 struct DeviceResourceAttr *next; /**< Pointer to the next attribute of the node in the configuration tree. */ 62 }; 63 64 /** 65 * @brief Defines a tree node in the configuration tree. 66 * 67 * The tree node information includes the node name, unique node ID, node attributes, parent node, child nodes, 68 * and sibling nodes. 69 */ 70 struct DeviceResourceNode { 71 const char *name; /**< Pointer to the node name */ 72 uint32_t hashValue; /**< Unique ID of a node */ 73 struct DeviceResourceAttr *attrData; /**< Pointer to the node attributes */ 74 struct DeviceResourceNode *parent; /**< Pointer to the parent node */ 75 struct DeviceResourceNode *child; /**< Pointer to a child node */ 76 struct DeviceResourceNode *sibling; /**< Pointer to a sibling node */ 77 }; 78 79 /** 80 * @brief Provides functions for obtaining information about the device resource configuration tree. 81 * 82 * This structure provides functions for obtaining information about the device resource configuration tree, 83 * including the root node, the <b>unit</b> attribute data, and the <b>String</b> attribute data. 84 * 85 * @since 1.0 86 * @version 1.0 87 */ 88 struct DeviceResourceIface { 89 /** 90 * @brief Obtains the root node of the configuration tree. 91 * 92 * When the driver framework is started, a configuration tree is created. You can use this function to obtain 93 * the root node of the configuration tree. 94 * 95 * @return Returns the root node of the configuration tree if the operation is successful; 96 * returns <b>NULL</b> otherwise. 97 * @since 1.0 98 * @version 1.0 99 */ 100 const struct DeviceResourceNode *(*GetRootNode)(void); 101 /** 102 * @brief Obtains the value of a <b>BOOL</b> attribute of a configuration tree node. 103 * 104 * @param node Indicates the pointer to the configuration tree node. 105 * @param attrName Indicates the pointer to the name of the attribute. 106 * 107 * @return Returns <b>true</b> if the operation is successful and the value of the <b>BOOL</b> attribute is 108 * <b>true</b>; returns <b>false</b> otherwise. 109 * @since 1.0 110 * @version 1.0 111 */ 112 bool (*GetBool)(const struct DeviceResourceNode *node, const char *attrName); 113 /** 114 * @brief Obtains the value of a <b>Uint8</b> attribute of a configuration tree node. 115 * 116 * @param node Indicates the pointer to the configuration tree node. 117 * @param attrName Indicates the pointer to the name of the attribute. 118 * @param value Indicates the pointer to the memory that stores the obtained data. The memory is applied 119 * by the user. 120 * @param def Indicates the value to fill into the memory pointed by <b>value</b> if the operation fails. 121 * 122 * @return Returns <b>0</b> if the attribute value is obtained successfully; returns a negative value otherwise. 123 * @since 1.0 124 * @version 1.0 125 */ 126 int32_t (*GetUint8)(const struct DeviceResourceNode *node, const char *attrName, uint8_t *value, uint8_t def); 127 /** 128 * @brief Obtains the value of a <b>Unit8</b> array attribute numbered <b>index</b> of a configuration tree node. 129 * 130 * @param node Indicates the pointer to the configuration tree node. 131 * @param attrName Indicates the pointer to the name of the array attribute. 132 * @param index Indicates the number of the index (counting from 0) where the value is to obtain. 133 * @param value Indicates the pointer to the memory that stores the obtained data. The memory is applied 134 * by the user. 135 * @param def Indicates the value to fill into the memory pointed by <b>value</b> if the operation fails. 136 * 137 * @return Returns <b>0</b> if the array attribute value is obtained successfully; returns a negative value 138 * otherwise. 139 * @since 1.0 140 * @version 1.0 141 */ 142 int32_t (*GetUint8ArrayElem)(const struct DeviceResourceNode *node, const char *attrName, uint32_t index, 143 uint8_t *value, uint8_t def); 144 /** 145 * @brief Obtains the value of a <b>Uint8</b> array attribute of a configuration tree node. 146 * 147 * @param node Indicates the pointer to the configuration tree node. 148 * @param attrName Indicates the pointer to the name of the array attribute. 149 * @param value Indicates the pointer to the array that stores the obtained data. The memory of the array is applied 150 * by the user. 151 * @param len Indicates the length of the array. 152 * @param def Indicates the value to fill into <b>value</b> if the operation fails. If the obtained attribute value 153 * contains 16-bit, 32-bit, or 64-bit data, the element corresponding to the 16-bit, 32-bit, or 64-bit data in the 154 * array is filled using the value of <b>def</b>, and the other elements are filled with the actual value obtained. 155 * If the failure is caused by other exceptions, the first element in the array is filled using the value of 156 * <b>def</b>. 157 * 158 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 159 * @since 1.0 160 * @version 1.0 161 */ 162 int32_t (*GetUint8Array)(const struct DeviceResourceNode *node, const char *attrName, uint8_t *value, uint32_t len, 163 uint8_t def); 164 /** 165 * @brief Obtains the value of a <b>Uint16</b> attribute of a configuration tree node. 166 * 167 * @param node Indicates the pointer to the configuration tree node. 168 * @param attrName Indicates the pointer to the name of the attribute. 169 * @param value Indicates the pointer to the memory that stores the obtained data. The memory is applied 170 * by the user. 171 * @param def Indicates the value to fill into the memory pointed by <b>value</b> if the operation fails. 172 * 173 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 174 * @since 1.0 175 * @version 1.0 176 */ 177 int32_t (*GetUint16)(const struct DeviceResourceNode *node, const char *attrName, uint16_t *value, uint16_t def); 178 /** 179 * @brief Obtains the value of a <b>Uint16</b> array attribute numbered <b>index</b> of a configuration tree node. 180 * 181 * @param node Indicates the pointer to the configuration tree node. 182 * @param attrName Indicates the pointer to the name of the array attribute. 183 * @param index Indicates the number of the index (counting from 0) where the value is to obtain. 184 * @param value Indicates the pointer to the memory that stores the obtained data. The memory is applied 185 * by the user. 186 * @param def Indicates the value to fill into the memory pointed by <b>value</b> if the operation fails. 187 * 188 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 189 * @since 1.0 190 * @version 1.0 191 */ 192 int32_t (*GetUint16ArrayElem)(const struct DeviceResourceNode *node, const char *attrName, uint32_t index, 193 uint16_t *value, uint16_t def); 194 /** 195 * @brief Obtains the values of a <b>Uint16</b> array attribute of a configuration tree node. 196 * 197 * @param node Indicates the pointer to the configuration tree node. 198 * @param attrName Indicates the pointer to the name of the array attribute. 199 * @param value Indicates the pointer to the array that stores the obtained data. The memory of the array is applied 200 * by the user. 201 * @param len Indicates the length of the array. 202 * @param def Indicates the value to fill into <b>value</b> if the operation fails. If the obtained attribute value 203 * contains 32-bit or 64-bit data, the element corresponding to the 32-bit or 64-bit data in the array is filled 204 * using the value of <b>def</b>, and the other elements are filled with the actual value obtained. If the failure 205 * is caused by other exceptions, the first element in the array is filled using the value of <b>def</b>. 206 * 207 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 208 * @since 1.0 209 * @version 1.0 210 */ 211 int32_t (*GetUint16Array)(const struct DeviceResourceNode *node, const char *attrName, uint16_t *value, 212 uint32_t len, uint16_t def); 213 /** 214 * @brief Obtains the value of a <b>Uint32</b> attribute of a configuration tree node. 215 * 216 * @param node Indicates the pointer to the configuration tree node. 217 * @param attrName Indicates the pointer to the name of the attribute. 218 * @param value Indicates the pointer to the memory that stores the obtained data. The memory is applied 219 * by the user. 220 * @param def Indicates the value to fill into the memory pointed by <b>value</b> if the operation fails. 221 * 222 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 223 * @since 1.0 224 * @version 1.0 225 */ 226 int32_t (*GetUint32)(const struct DeviceResourceNode *node, const char *attrName, uint32_t *value, uint32_t def); 227 /** 228 * @brief Obtains the value of a <b>Uint32</b> array attribute numbered <b>index</b> of a configuration tree node. 229 * 230 * @param node Indicates the pointer to the configuration tree node. 231 * @param attrName Indicates the pointer to the name of the array attribute. 232 * @param index Indicates the number of the index (counting from 0) where the value is to obtain. 233 * @param value Indicates the pointer to the memory that stores the obtained data. The memory is applied 234 * by the user. 235 * @param def Indicates the value to fill into the memory pointed by <b>value</b> if the operation fails. 236 * 237 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 238 * @since 1.0 239 * @version 1.0 240 */ 241 int32_t (*GetUint32ArrayElem)(const struct DeviceResourceNode *node, const char *attrName, uint32_t index, 242 uint32_t *value, uint32_t def); 243 /** 244 * @brief Obtains the values of a <b>Uint32</b> array attribute of a configuration tree node. 245 * 246 * @param node Indicates the pointer to the configuration tree node. 247 * @param attrName Indicates the pointer to the name of the array attribute. 248 * @param value Indicates the pointer to an array that stores the obtained data. 249 * @param len Indicates the pointer to the array that stores the obtained data. The memory of the array is applied 250 * by the user. 251 * @param def Indicates the value to fill into <b>value</b> if the operation fails. If the obtained attribute value 252 * contains 64-bit data, the element corresponding to the 64-bit data in the array is filled using the value of 253 * <b>def</b>, and the other elements are filled with the actual value obtained. If the failure is caused by other 254 * exceptions, the first element in the array is filled using the value of <b>def</b>. 255 * 256 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 257 * @since 1.0 258 * @version 1.0 259 */ 260 int32_t (*GetUint32Array)(const struct DeviceResourceNode *node, const char *attrName, uint32_t *value, 261 uint32_t len, uint32_t def); 262 /** 263 * @brief Obtains the value of a <b>Uint64</b> attribute of a configuration tree node. 264 * 265 * @param node Indicates the pointer to the configuration tree node. 266 * @param attrName Indicates the pointer to the name of the attribute. 267 * @param value Indicates the pointer to the memory that stores the obtained data. The memory is applied 268 * by the user. 269 * @param def Indicates the value to fill into the memory pointed by <b>value</b> if the operation fails. 270 * 271 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 272 * @since 1.0 273 * @version 1.0 274 */ 275 int32_t (*GetUint64)(const struct DeviceResourceNode *node, const char *attrName, uint64_t *value, uint64_t def); 276 /** 277 * @brief Obtains the value of a <b>Uint64</b> array attribute numbered <b>index</b> of a configuration tree node. 278 * 279 * @param node Indicates the pointer to the configuration tree node. 280 * @param attrName Indicates the pointer to the name of the array attribute. 281 * @param index Indicates the number of the index (counting from 0) where the value is to obtain. 282 * @param value Indicates the pointer to the memory that stores the obtained data. The memory is applied 283 * by the user. 284 * @param def Indicates the value to fill into the memory pointed by <b>value</b> if the operation fails. 285 * 286 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 287 * @since 1.0 288 * @version 1.0 289 */ 290 int32_t (*GetUint64ArrayElem)(const struct DeviceResourceNode *node, const char *attrName, uint32_t index, 291 uint64_t *value, uint64_t def); 292 /** 293 * @brief Obtains the values of a <b>Uint64</b> array attribute of a configuration tree node. 294 * 295 * @param node Indicates the pointer to the configuration tree node. 296 * @param attrName Indicates the pointer to the name of the array attribute. 297 * @param value Indicates the pointer to the array that stores the obtained data. The memory of the array is applied 298 * by the user. 299 * @param len Indicates the length of the array. 300 * @param def Indicates the value to fill into the first element in the <b>value</b> array if the operation fails. 301 * 302 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 303 * @since 1.0 304 * @version 1.0 305 */ 306 int32_t (*GetUint64Array)(const struct DeviceResourceNode *node, const char *attrName, uint64_t *value, 307 uint32_t len, uint64_t def); 308 /** 309 * @brief Obtains the value of a <b>String</b> attribute of a configuration tree node. 310 * 311 * @param node Indicates the pointer to the configuration tree node. 312 * @param attrName Indicates the pointer to the name of the attribute. 313 * @param value Indicates the double pointer to the memory where the obtained data is stored. The string memory is 314 * provided by the function implementer. Users only need to transfer the double pointer. The memory cannot be 315 * released after being used. 316 * @param def Indicates the value to be passed to <b>value</b> if the operation fails. 317 * 318 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 319 * @since 1.0 320 * @version 1.0 321 */ 322 int32_t (*GetString)(const struct DeviceResourceNode *node, const char *attrName, const char **value, 323 const char *def); 324 /** 325 * @brief Obtains the value of a <b>String</b> array attribute numbered <b>index</b> of a configuration tree node. 326 * 327 * @param node Indicates the pointer to the configuration tree node. 328 * @param attrName Indicates the pointer to the name of the array attribute. 329 * @param index Indicates the number of the index (counting from 0) where the value is to obtain. 330 * @param value Indicates the double pointer to the memory where the obtained data is stored. The string memory is 331 * provided by the function implementer. Users only need to transfer the double pointer. The memory cannot be 332 * released after being used. 333 * @param def def Indicates the value to be passed to <b>value</b> if the operation fails. 334 * 335 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 336 * @since 1.0 337 * @version 1.0 338 */ 339 int32_t (*GetStringArrayElem)(const struct DeviceResourceNode *node, const char *attrName, uint32_t index, 340 const char **value, const char *def); 341 /** 342 * @brief Obtains the number of values for an array attribute of a configuration tree node. 343 * 344 * @param node Indicates the pointer to the configuration tree node. 345 * @param attrName Indicates the pointer to the name of the array attribute. 346 * 347 * @return Returns the number of values for an array attribute if the operation is successful; 348 * return a negative value otherwise. 349 * @since 1.0 350 * @version 1.0 351 */ 352 int32_t (*GetElemNum)(const struct DeviceResourceNode *node, const char *attrName); 353 /** 354 * @brief Obtains a specified child node of the current tree node based on the value of a specific reserved 355 * attribute (for example, the reserved attribute of the HCS is <b>match_attr</b>). 356 * 357 * There is a specific reserved attribute in the syntax of the device resource configuration source file. 358 * If this attribute is set for a tree node, you can obtain the node based on the attribute value. 359 * Users can set the attribute value based on the usage of their own nodes, but they must ensure that the attribute 360 * values are unique. 361 * 362 * @param node Indicates the pointer to the node for whom a child node is to be obtained. The node can be the child 363 * node's parent node or grandparent node. 364 * @param attrValue Indicates the pointer to the value of the reserved attribute configured for the child node. 365 * 366 * @return Returns the target node if the operation is successful; returns <b>NULL</b> otherwise. 367 * @since 1.0 368 * @version 1.0 369 */ 370 const struct DeviceResourceNode *(*GetNodeByMatchAttr)(const struct DeviceResourceNode *node, 371 const char *attrValue); 372 /** 373 * @brief Obtains the child node with a specified node name from a parent node. 374 * 375 * @param node Indicates the pointer to the parent node. 376 * @param nodeName Indicates the pointer to the name of the child node to obtain. 377 * 378 * @return Returns the child nodes if the operation is successful; returns <b>NULL</b> otherwise. 379 * @since 1.0 380 * @version 1.0 381 */ 382 const struct DeviceResourceNode *(*GetChildNode)(const struct DeviceResourceNode *node, const char *nodeName); 383 /** 384 * @brief Obtains the node that is specified by a node-type attribute of a configuration tree node. 385 * 386 * If the attribute value is a configuration tree node, the path of the node is converted to a globally unique 387 * <b>hashValue</b> when the device resource source file is compiled (for example, the compilation tool of the HCS 388 * source file is hc-gen). For details about the <b>hashValue</b>, see {@link struct DeviceResourceNode}. 389 * When you obtain a tree node using the node-type attribute, you obtain the <b>hashValue</b> through the node-type 390 * attribute first, and then traverse the tree to obtain the tree node corresponding to the <b>hashValue</b>. 391 * 392 * @param node Indicates the pointer to the tree node whose attribute is to obtain. 393 * @param attrName Indicates the pointer to the name of attribute whose value is a node path. 394 * @return Returns the target node if the operation is successful; returns <b>NULL</b> otherwise. 395 * @since 1.0 396 * @version 1.0 397 */ 398 const struct DeviceResourceNode *(*GetNodeByRefAttr)(const struct DeviceResourceNode *node, const char *attrName); 399 }; 400 401 /** 402 * @brief Obtains the device resource interface handle of the corresponding configuration tree type. 403 * 404 * You can use the obtained handle to use the device resource interface. 405 * 406 * @param type Indicates the type of the device resource interface handle to obtain. 407 * 408 * @return Returns the device resource interface handle if the operation is successful; returns <b>NULL</b> otherwise. 409 * @since 1.0 410 * @version 1.0 411 */ 412 struct DeviceResourceIface *DeviceResourceGetIfaceInstance(DeviceResourceType type); 413 414 /** 415 * @brief Traverses the attributes of the current configuration tree node. 416 * 417 * This operation is a <b>for</b> loop in essence. 418 * 419 * @param node Indicates the configuration tree node to traverse. 420 * @param attr Indicates the traversed attributes. 421 * @since 1.0 422 * @version 1.0 423 */ 424 #define DEV_RES_NODE_FOR_EACH_ATTR(node, attr) \ 425 for ((attr) = (node)->attrData; (attr) != NULL; (attr) = (attr)->next) 426 427 /** 428 * @brief Traverses the child nodes of the current configuration tree node. 429 * 430 * This operation is a <b>for</b> loop in essence. 431 * 432 * @param node Indicates the configuration tree node to traverse. 433 * @param childNode Indicates the traversed child nodes. 434 * @since 1.0 435 * @version 1.0 436 */ 437 #define DEV_RES_NODE_FOR_EACH_CHILD_NODE(node, childNode) \ 438 for ((childNode) = (node)->child; (childNode) != NULL; (childNode) = (childNode)->sibling) 439 440 #ifdef __cplusplus 441 #if __cplusplus 442 } 443 #endif 444 #endif /* __cplusplus */ 445 446 #endif /* DEVICE_RESOURCE_IF_H */ 447 /** @} */ 448