1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright 2018, Olivier MATZ <zer0@droids-corp.org>
13 #ifndef EC_COUNT_OF //XXX
14 #define EC_COUNT_OF(x) ((sizeof(x)/sizeof(0[x])) / \
15 ((size_t)(!(sizeof(x) % sizeof(0[x])))))
22 * The type identifier for a config value.
25 EC_CONFIG_TYPE_NONE = 0,
28 EC_CONFIG_TYPE_UINT64,
29 EC_CONFIG_TYPE_STRING,
36 * Structure describing the format of a configuration value.
38 * This structure is used in a const array which is referenced by a
39 * struct ec_config. Each entry of the array represents a key/value
40 * storage of the configuration dictionary.
42 struct ec_config_schema {
43 const char *key; /**< The key string (NULL for list elts). */
44 const char *desc; /**< A description of the value. */
45 enum ec_config_type type; /**< Type of the value */
47 /** If type is dict or list, the schema of the dict or list
48 * elements. Else must be NULL. */
49 const struct ec_config_schema *subschema;
52 TAILQ_HEAD(ec_config_list, ec_config);
55 * Structure storing the configuration data.
58 /** type of value stored in the union */
59 enum ec_config_type type;
62 bool boolean; /** Boolean value */
63 int64_t i64; /** Signed integer value */
64 uint64_t u64; /** Unsigned integer value */
65 char *string; /** String value */
66 struct ec_node *node; /** Node value */
67 struct ec_keyval *dict; /** Hash table value */
68 struct ec_config_list list; /** List value */
72 * Next in list, only valid if type is list.
74 TAILQ_ENTRY(ec_config) next;
80 * Validate a configuration schema array.
83 * Pointer to the first element of the schema array. The array
84 * must be terminated by a sentinel entry (type == EC_CONFIG_TYPE_NONE).
86 * 0 if the schema is valid, or -1 on error (errno is set).
88 int ec_config_schema_validate(const struct ec_config_schema *schema);
91 * Dump a configuration schema array.
94 * Output stream on which the dump will be sent.
96 * Pointer to the first element of the schema array. The array
97 * must be terminated by a sentinel entry (type == EC_CONFIG_TYPE_NONE).
99 void ec_config_schema_dump(FILE *out, const struct ec_config_schema *schema);
102 * Find a schema entry matching the key.
104 * Browse the schema array and lookup for the given key.
107 * Pointer to the first element of the schema array. The array
108 * must be terminated by a sentinel entry (type == EC_CONFIG_TYPE_NONE).
110 * The schema entry if it matches a key, or NULL if not found.
112 const struct ec_config_schema *
113 ec_config_schema_lookup(const struct ec_config_schema *schema,
117 * Get the type of a schema entry.
120 * Pointer to an element of the schema array.
122 * The type of the schema entry.
125 ec_config_schema_type(const struct ec_config_schema *schema_elt);
128 * Get the subschema of a schema entry.
131 * Pointer to an element of the schema array.
133 * The subschema if any, or NULL.
135 const struct ec_config_schema *
136 ec_config_schema_sub(const struct ec_config_schema *schema_elt);
139 * Check if a key name is reserved in a config dict.
141 * Some key names are reserved and should not be used in configs.
144 * The name of the key to test.
146 * True if the key name is reserved and must not be used, else false.
148 bool ec_config_key_is_reserved(const char *name);
151 * Array of reserved key names.
153 extern const char *ec_config_reserved_keys[];
159 * Get the type of the configuration.
164 * The configuration type.
166 enum ec_config_type ec_config_get_type(const struct ec_config *config);
169 * Create a boolean configuration value.
172 * The boolean value to be set.
174 * The configuration object, or NULL on error (errno is set).
176 struct ec_config *ec_config_bool(bool boolean);
179 * Create a signed integer configuration value.
182 * The signed integer value to be set.
184 * The configuration object, or NULL on error (errno is set).
186 struct ec_config *ec_config_i64(int64_t i64);
189 * Create an unsigned configuration value.
192 * The unsigned integer value to be set.
194 * The configuration object, or NULL on error (errno is set).
196 struct ec_config *ec_config_u64(uint64_t u64);
199 * Create a string configuration value.
202 * The string value to be set. The string is copied into the
203 * configuration object.
205 * The configuration object, or NULL on error (errno is set).
207 struct ec_config *ec_config_string(const char *string);
210 * Create a node configuration value.
213 * The node pointer to be set. The node is "consumed" by
214 * the function and should not be used by the caller, even
215 * on error. The caller can use ec_node_clone() to keep a
216 * reference on the node.
218 * The configuration object, or NULL on error (errno is set).
220 struct ec_config *ec_config_node(struct ec_node *node);
223 * Create a hash table configuration value.
226 * A configuration object containing an empty hash table, or NULL on
227 * error (errno is set).
229 struct ec_config *ec_config_dict(void);
232 * Create a list configuration value.
235 * The configuration object containing an empty list, or NULL on
236 * error (errno is set).
238 struct ec_config *ec_config_list(void);
241 * Add a config object into a list.
244 * The list configuration in which the value will be added.
246 * The value configuration to add in the list. The value object
247 * will be freed when freeing the list object. On error, the
248 * value object is also freed.
250 * 0 on success, else -1 (errno is set).
252 int ec_config_list_add(struct ec_config *list, struct ec_config *value);
255 * Remove an element from a list.
257 * The element is freed and should not be accessed.
260 * The list configuration.
262 * The element to remove from the list.
264 * 0 on success, -1 on error (errno is set).
266 int ec_config_list_del(struct ec_config *list, struct ec_config *config);
269 * Validate a configuration.
272 * A hash table configuration to validate.
274 * Pointer to the first element of the schema array. The array
275 * must be terminated by a sentinel entry (type == EC_CONFIG_TYPE_NONE).
277 * 0 on success, -1 on error (errno is set).
279 int ec_config_validate(const struct ec_config *dict,
280 const struct ec_config_schema *schema);
283 * Set a value in a hash table configuration
286 * A hash table configuration to validate.
290 * The value to set. The value object will be freed when freeing the
291 * dict object. On error, the value object is also freed.
293 * 0 on success, -1 on error (errno is set).
295 int ec_config_dict_set(struct ec_config *dict, const char *key,
296 struct ec_config *value);
299 * Remove an element from a hash table configuration.
301 * The element is freed and should not be accessed.
304 * A hash table configuration to validate.
306 * The key of the configuration to delete.
308 * 0 on success, -1 on error (errno is set).
310 int ec_config_dict_del(struct ec_config *config, const char *key);
313 * Compare two configurations.
315 int ec_config_cmp(const struct ec_config *config1,
316 const struct ec_config *config2);
319 * Get configuration value.
321 struct ec_config *ec_config_dict_get(const struct ec_config *config,
325 * Get the first element of a list.
328 * for (config = ec_config_list_iter(list);
330 * config = ec_config_list_next(list, config)) {
335 * The list configuration to iterate.
337 * The first configuration element, or NULL on error (errno is set).
339 struct ec_config *ec_config_list_first(struct ec_config *list);
342 * Get next element in list.
345 * The list configuration beeing iterated.
347 * The current configuration element.
349 * The next configuration element, or NULL if there is no more element.
352 ec_config_list_next(struct ec_config *list, struct ec_config *config);
355 * Free a configuration.
358 * The element to free.
360 void ec_config_free(struct ec_config *config);
363 * Compare two configurations.
366 * 0 if the configurations are equal, else -1.
368 int ec_config_cmp(const struct ec_config *value1,
369 const struct ec_config *value2);
372 * Duplicate a configuration.
375 * The configuration to duplicate.
377 * The duplicated configuration, or NULL on error (errno is set).
380 ec_config_dup(const struct ec_config *config);
383 * Dump a configuration.
386 * Output stream on which the dump will be sent.
388 * The configuration to dump.
390 void ec_config_dump(FILE *out, const struct ec_config *config);