1 #ifndef _IPXE_SETTINGS_H
2 #define _IPXE_SETTINGS_H
6 * Configuration settings
10 FILE_LICENCE ( GPL2_OR_LATER );
13 #include <ipxe/tables.h>
14 #include <ipxe/list.h>
15 #include <ipxe/refcnt.h>
26 * This is the human-readable name for the setting.
30 const char *description;
33 * This identifies the type of setting (e.g. string, IPv4
36 const struct setting_type *type;
37 /** Setting tag, if applicable
39 * The setting tag is a numerical description of the setting
40 * (such as a DHCP option number, or an SMBIOS structure and
44 /** Setting scope (or NULL)
46 * For historic reasons, a NULL scope with a non-zero tag
47 * indicates a DHCPv4 option setting.
49 const struct settings_scope *scope;
52 /** Configuration setting table */
53 #define SETTINGS __table ( struct setting, "settings" )
55 /** Declare a configuration setting */
56 #define __setting( setting_order, name ) \
57 __table_entry ( SETTINGS, setting_order.name )
59 /** @defgroup setting_order Setting ordering
63 #define SETTING_NETDEV 01 /**< Network device settings */
64 #define SETTING_NETDEV_EXTRA 02 /**< Network device additional settings */
65 #define SETTING_IP 03 /**< IPv4 settings */
66 #define SETTING_IP_EXTRA 04 /**< IPv4 additional settings */
67 #define SETTING_BOOT 05 /**< Generic boot settings */
68 #define SETTING_BOOT_EXTRA 06 /**< Generic boot additional settings */
69 #define SETTING_SANBOOT 07 /**< SAN boot settings */
70 #define SETTING_SANBOOT_EXTRA 08 /**< SAN boot additional settings */
71 #define SETTING_HOST 09 /**< Host identity settings */
72 #define SETTING_HOST_EXTRA 10 /**< Host identity additional settings */
73 #define SETTING_AUTH 11 /**< Authentication settings */
74 #define SETTING_AUTH_EXTRA 12 /**< Authentication additional settings */
75 #define SETTING_CRYPTO 13 /**< Cryptography settings */
76 #define SETTING_MISC 14 /**< Miscellaneous settings */
80 /** Settings block operations */
81 struct settings_operations {
82 /** Redirect to underlying settings block (if applicable)
84 * @v settings Settings block
85 * @ret settings Underlying settings block
87 struct settings * ( * redirect ) ( struct settings *settings );
88 /** Check applicability of setting
90 * @v settings Settings block
92 * @ret applies Setting applies within this settings block
94 int ( * applies ) ( struct settings *settings,
95 const struct setting *setting );
96 /** Store value of setting
98 * @v settings Settings block
99 * @v setting Setting to store
100 * @v data Setting data, or NULL to clear setting
101 * @v len Length of setting data
102 * @ret rc Return status code
104 int ( * store ) ( struct settings *settings,
105 const struct setting *setting,
106 const void *data, size_t len );
107 /** Fetch value of setting
109 * @v settings Settings block
110 * @v setting Setting to fetch
111 * @v data Buffer to fill with setting data
112 * @v len Length of buffer
113 * @ret len Length of setting data, or negative error
115 * The actual length of the setting will be returned even if
116 * the buffer was too small.
118 int ( * fetch ) ( struct settings *settings, struct setting *setting,
119 void *data, size_t len );
120 /** Clear settings block
122 * @v settings Settings block
124 void ( * clear ) ( struct settings *settings );
127 /** A settings block */
129 /** Reference counter */
130 struct refcnt *refcnt;
133 /** Parent settings block */
134 struct settings *parent;
135 /** Sibling settings blocks */
136 struct list_head siblings;
137 /** Child settings blocks */
138 struct list_head children;
139 /** Settings block operations */
140 struct settings_operations *op;
141 /** Default scope for numerical settings constructed for this block */
142 const struct settings_scope *default_scope;
148 * Users can construct tags for settings that are not explicitly known
149 * to iPXE using the generic syntax for numerical settings. For
150 * example, the setting name "60" will be interpreted as referring to
151 * DHCP option 60 (the vendor class identifier).
153 * This creates a potential for namespace collisions, since the
154 * interpretation of the numerical description will vary according to
155 * the settings block. When a user attempts to fetch a generic
156 * numerical setting, we need to ensure that only the intended
157 * settings blocks interpret this numerical description. (For
158 * example, we do not want to attempt to retrieve the subnet mask from
159 * SMBIOS, or the system UUID from DHCP.)
161 * This potential problem is resolved by including a user-invisible
162 * "scope" within the definition of each setting. Settings blocks may
163 * use this to determine whether or not the setting is applicable.
164 * Any settings constructed from a numerical description
165 * (e.g. "smbios/1.4.0") will be assigned the default scope of the
166 * settings block specified in the description (e.g. "smbios"); this
167 * provides behaviour matching the user's expectations in most
170 struct settings_scope {
173 * This is included only to ensure that pointers to different
174 * scopes always compare differently.
177 } __attribute__ (( packed ));
182 * This represents a type of setting (e.g. string, IPv4 address,
185 struct setting_type {
188 * This is the name exposed to the user (e.g. "string").
191 /** Parse formatted string to setting value
193 * @v type Setting type
194 * @v value Formatted setting value
195 * @v buf Buffer to contain raw value
196 * @v len Length of buffer
197 * @ret len Length of raw value, or negative error
199 int ( * parse ) ( const struct setting_type *type, const char *value,
200 void *buf, size_t len );
201 /** Format setting value as a string
203 * @v type Setting type
204 * @v raw Raw setting value
205 * @v raw_len Length of raw setting value
206 * @v buf Buffer to contain formatted value
207 * @v len Length of buffer
208 * @ret len Length of formatted value, or negative error
210 int ( * format ) ( const struct setting_type *type, const void *raw,
211 size_t raw_len, char *buf, size_t len );
212 /** Convert number to setting value
214 * @v type Setting type
215 * @v value Numeric value
216 * @v buf Buffer to contain raw value
217 * @v len Length of buffer
218 * @ret len Length of raw value, or negative error
220 int ( * denumerate ) ( const struct setting_type *type,
222 void *buf, size_t len );
223 /** Convert setting value to number
225 * @v type Setting type
226 * @v raw Raw setting value
227 * @v raw_len Length of raw setting value
228 * @v value Numeric value to fill in
229 * @ret rc Return status code
231 int ( * numerate ) ( const struct setting_type *type, const void *raw,
232 size_t raw_len, unsigned long *value );
235 /** Configuration setting type table */
236 #define SETTING_TYPES __table ( struct setting_type, "setting_types" )
238 /** Declare a configuration setting type */
239 #define __setting_type __table_entry ( SETTING_TYPES, 01 )
242 * A settings applicator
245 struct settings_applicator {
246 /** Apply updated settings
248 * @ret rc Return status code
250 int ( * apply ) ( void );
253 /** Settings applicator table */
254 #define SETTINGS_APPLICATORS \
255 __table ( struct settings_applicator, "settings_applicators" )
257 /** Declare a settings applicator */
258 #define __settings_applicator __table_entry ( SETTINGS_APPLICATORS, 01 )
260 /** A built-in setting */
261 struct builtin_setting {
263 const struct setting *setting;
264 /** Fetch setting value
266 * @v data Buffer to fill with setting data
267 * @v len Length of buffer
268 * @ret len Length of setting data, or negative error
270 int ( * fetch ) ( void *data, size_t len );
273 /** Built-in settings table */
274 #define BUILTIN_SETTINGS __table ( struct builtin_setting, "builtin_settings" )
276 /** Declare a built-in setting */
277 #define __builtin_setting __table_entry ( BUILTIN_SETTINGS, 01 )
279 /** Built-in setting scope */
280 extern const struct settings_scope builtin_scope;
282 /** IPv6 setting scope */
283 extern const struct settings_scope ipv6_scope;
286 * A generic settings block
289 struct generic_settings {
290 /** Settings block */
291 struct settings settings;
292 /** List of generic settings */
293 struct list_head list;
296 /** A child settings block locator function */
297 typedef struct settings * ( *get_child_settings_t ) ( struct settings *settings,
299 extern struct settings_operations generic_settings_operations;
300 extern int generic_settings_store ( struct settings *settings,
301 const struct setting *setting,
302 const void *data, size_t len );
303 extern int generic_settings_fetch ( struct settings *settings,
304 struct setting *setting,
305 void *data, size_t len );
306 extern void generic_settings_clear ( struct settings *settings );
308 extern int register_settings ( struct settings *settings,
309 struct settings *parent, const char *name );
310 extern void unregister_settings ( struct settings *settings );
312 extern struct settings * settings_target ( struct settings *settings );
313 extern int setting_applies ( struct settings *settings,
314 const struct setting *setting );
315 extern int store_setting ( struct settings *settings,
316 const struct setting *setting,
317 const void *data, size_t len );
318 extern int fetch_setting ( struct settings *settings,
319 const struct setting *setting,
320 struct settings **origin, struct setting *fetched,
321 void *data, size_t len );
322 extern int fetch_setting_copy ( struct settings *settings,
323 const struct setting *setting,
324 struct settings **origin,
325 struct setting *fetched, void **data );
326 extern int fetch_raw_setting ( struct settings *settings,
327 const struct setting *setting,
328 void *data, size_t len );
329 extern int fetch_raw_setting_copy ( struct settings *settings,
330 const struct setting *setting,
332 extern int fetch_string_setting ( struct settings *settings,
333 const struct setting *setting,
334 char *data, size_t len );
335 extern int fetch_string_setting_copy ( struct settings *settings,
336 const struct setting *setting,
338 extern int fetch_ipv4_array_setting ( struct settings *settings,
339 const struct setting *setting,
340 struct in_addr *inp, unsigned int count );
341 extern int fetch_ipv4_setting ( struct settings *settings,
342 const struct setting *setting,
343 struct in_addr *inp );
344 extern int fetch_ipv6_array_setting ( struct settings *settings,
345 const struct setting *setting,
346 struct in6_addr *inp, unsigned int count);
347 extern int fetch_ipv6_setting ( struct settings *settings,
348 const struct setting *setting,
349 struct in6_addr *inp );
350 extern int fetch_int_setting ( struct settings *settings,
351 const struct setting *setting, long *value );
352 extern int fetch_uint_setting ( struct settings *settings,
353 const struct setting *setting,
354 unsigned long *value );
355 extern long fetch_intz_setting ( struct settings *settings,
356 const struct setting *setting );
357 extern unsigned long fetch_uintz_setting ( struct settings *settings,
358 const struct setting *setting );
359 extern int fetch_uuid_setting ( struct settings *settings,
360 const struct setting *setting,
362 extern void clear_settings ( struct settings *settings );
363 extern int setting_cmp ( const struct setting *a, const struct setting *b );
365 extern struct settings * find_child_settings ( struct settings *parent,
367 extern struct settings * autovivify_child_settings ( struct settings *parent,
369 extern const char * settings_name ( struct settings *settings );
370 extern struct settings * find_settings ( const char *name );
371 extern struct setting * find_setting ( const char *name );
372 extern int parse_setting_name ( char *name, get_child_settings_t get_child,
373 struct settings **settings,
374 struct setting *setting );
375 extern int setting_name ( struct settings *settings,
376 const struct setting *setting,
377 char *buf, size_t len );
378 extern int setting_format ( const struct setting_type *type, const void *raw,
379 size_t raw_len, char *buf, size_t len );
380 extern int setting_parse ( const struct setting_type *type, const char *value,
381 void *buf, size_t len );
382 extern int setting_numerate ( const struct setting_type *type, const void *raw,
383 size_t raw_len, unsigned long *value );
384 extern int setting_denumerate ( const struct setting_type *type,
385 unsigned long value, void *buf, size_t len );
386 extern int fetchf_setting ( struct settings *settings,
387 const struct setting *setting,
388 struct settings **origin, struct setting *fetched,
389 char *buf, size_t len );
390 extern int fetchf_setting_copy ( struct settings *settings,
391 const struct setting *setting,
392 struct settings **origin,
393 struct setting *fetched, char **value );
394 extern int storef_setting ( struct settings *settings,
395 const struct setting *setting, const char *value );
396 extern int fetchn_setting ( struct settings *settings,
397 const struct setting *setting,
398 struct settings **origin, struct setting *fetched,
399 unsigned long *value );
400 extern int storen_setting ( struct settings *settings,
401 const struct setting *setting,
402 unsigned long value );
403 extern char * expand_settings ( const char *string );
405 extern const struct setting_type setting_type_string __setting_type;
406 extern const struct setting_type setting_type_uristring __setting_type;
407 extern const struct setting_type setting_type_ipv4 __setting_type;
408 extern const struct setting_type setting_type_ipv6 __setting_type;
409 extern const struct setting_type setting_type_int8 __setting_type;
410 extern const struct setting_type setting_type_int16 __setting_type;
411 extern const struct setting_type setting_type_int32 __setting_type;
412 extern const struct setting_type setting_type_uint8 __setting_type;
413 extern const struct setting_type setting_type_uint16 __setting_type;
414 extern const struct setting_type setting_type_uint32 __setting_type;
415 extern const struct setting_type setting_type_hex __setting_type;
416 extern const struct setting_type setting_type_hexhyp __setting_type;
417 extern const struct setting_type setting_type_hexraw __setting_type;
418 extern const struct setting_type setting_type_uuid __setting_type;
419 extern const struct setting_type setting_type_busdevfn __setting_type;
420 extern const struct setting_type setting_type_dnssl __setting_type;
422 extern const struct setting
423 ip_setting __setting ( SETTING_IP, ip );
424 extern const struct setting
425 netmask_setting __setting ( SETTING_IP, netmask );
426 extern const struct setting
427 gateway_setting __setting ( SETTING_IP, gateway );
428 extern const struct setting
429 dns_setting __setting ( SETTING_IP_EXTRA, dns );
430 extern const struct setting
431 hostname_setting __setting ( SETTING_HOST, hostname );
432 extern const struct setting
433 domain_setting __setting ( SETTING_IP_EXTRA, domain );
434 extern const struct setting
435 filename_setting __setting ( SETTING_BOOT, filename );
436 extern const struct setting
437 root_path_setting __setting ( SETTING_SANBOOT, root-path );
438 extern const struct setting
439 username_setting __setting ( SETTING_AUTH, username );
440 extern const struct setting
441 password_setting __setting ( SETTING_AUTH, password );
442 extern const struct setting
443 priority_setting __setting ( SETTING_MISC, priority );
444 extern const struct setting
445 uuid_setting __setting ( SETTING_HOST, uuid );
446 extern const struct setting
447 next_server_setting __setting ( SETTING_BOOT, next-server );
448 extern const struct setting
449 mac_setting __setting ( SETTING_NETDEV, mac );
450 extern const struct setting
451 busid_setting __setting ( SETTING_NETDEV, busid );
452 extern const struct setting
453 user_class_setting __setting ( SETTING_HOST_EXTRA, user-class );
456 * Initialise a settings block
458 * @v settings Settings block
459 * @v op Settings block operations
460 * @v refcnt Containing object reference counter, or NULL
461 * @v default_scope Default scope
463 static inline void settings_init ( struct settings *settings,
464 struct settings_operations *op,
465 struct refcnt *refcnt,
466 const struct settings_scope *default_scope ){
467 INIT_LIST_HEAD ( &settings->siblings );
468 INIT_LIST_HEAD ( &settings->children );
470 settings->refcnt = refcnt;
471 settings->default_scope = default_scope;
475 * Initialise a settings block
477 * @v generics Generic settings block
478 * @v refcnt Containing object reference counter, or NULL
480 static inline void generic_settings_init ( struct generic_settings *generics,
481 struct refcnt *refcnt ) {
482 settings_init ( &generics->settings, &generic_settings_operations,
484 INIT_LIST_HEAD ( &generics->list );
490 * @v settings Settings block
491 * @v setting Setting to delete
492 * @ret rc Return status code
494 static inline int delete_setting ( struct settings *settings,
495 const struct setting *setting ) {
496 return store_setting ( settings, setting, NULL, 0 );
500 * Check existence of predefined setting
502 * @v settings Settings block, or NULL to search all blocks
503 * @v setting Setting to fetch
504 * @ret exists Setting exists
506 static inline int setting_exists ( struct settings *settings,
507 const struct setting *setting ) {
508 return ( fetch_setting ( settings, setting, NULL, NULL,
512 #endif /* _IPXE_SETTINGS_H */