1 #ifndef _IPXE_SETTINGS_H
2 #define _IPXE_SETTINGS_H
3
4 /** @file
5 *
6 * Configuration settings
7 *
8 */
9
10 FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
11
12 #include <stdint.h>
13 #include <ipxe/tables.h>
14 #include <ipxe/list.h>
15 #include <ipxe/refcnt.h>
16
17 struct settings;
18 struct in_addr;
19 struct in6_addr;
20 union uuid;
21
22 /** A setting */
23 struct setting {
24 /** Name
25 *
26 * This is the human-readable name for the setting.
27 */
28 const char *name;
29 /** Description */
30 const char *description;
31 /** Setting type
32 *
33 * This identifies the type of setting (e.g. string, IPv4
34 * address, etc.).
35 */
36 const struct setting_type *type;
37 /** Setting tag, if applicable
38 *
39 * The setting tag is a numerical description of the setting
40 * (such as a DHCP option number, or an SMBIOS structure and
41 * field number).
42 */
43 uint64_t tag;
44 /** Setting scope (or NULL)
45 *
46 * For historic reasons, a NULL scope with a non-zero tag
47 * indicates a DHCPv4 option setting.
48 */
49 const struct settings_scope *scope;
50 };
51
52 /** Configuration setting table */
53 #define SETTINGS __table ( struct setting, "settings" )
54
55 /** Declare a configuration setting */
56 #define __setting( setting_order, name ) \
57 __table_entry ( SETTINGS, setting_order.name )
58
59 /** @defgroup setting_order Setting ordering
60 * @{
61 */
62
63 #define SETTING_NETDEV 01 /**< Network device settings */
64 #define SETTING_NETDEV_EXTRA 02 /**< Network device additional settings */
65 #define SETTING_IP4 03 /**< IPv4 settings */
66 #define SETTING_IP4_EXTRA 04 /**< IPv4 additional settings */
67 #define SETTING_IP6 05 /**< IPv6 settings */
68 #define SETTING_IP6_EXTRA 06 /**< IPv6 additional settings */
69 #define SETTING_IP 07 /**< IPv4 settings */
70 #define SETTING_IP_EXTRA 08 /**< IPv4 additional settings */
71 #define SETTING_BOOT 09 /**< Generic boot settings */
72 #define SETTING_BOOT_EXTRA 10 /**< Generic boot additional settings */
73 #define SETTING_SANBOOT 11 /**< SAN boot settings */
74 #define SETTING_SANBOOT_EXTRA 12 /**< SAN boot additional settings */
75 #define SETTING_HOST 13 /**< Host identity settings */
76 #define SETTING_HOST_EXTRA 14 /**< Host identity additional settings */
77 #define SETTING_AUTH 15 /**< Authentication settings */
78 #define SETTING_AUTH_EXTRA 16 /**< Authentication additional settings */
79 #define SETTING_CRYPTO 17 /**< Cryptography settings */
80 #define SETTING_MISC 18 /**< Miscellaneous settings */
81
82 /** @} */
83
84 /** Settings block operations */
85 struct settings_operations {
86 /** Redirect to underlying settings block (if applicable)
87 *
88 * @v settings Settings block
89 * @ret settings Underlying settings block
90 */
91 struct settings * ( * redirect ) ( struct settings *settings );
92 /** Check applicability of setting
93 *
94 * @v settings Settings block
95 * @v setting Setting
96 * @ret applies Setting applies within this settings block
97 */
98 int ( * applies ) ( struct settings *settings,
99 const struct setting *setting );
100 /** Store value of setting
101 *
102 * @v settings Settings block
103 * @v setting Setting to store
104 * @v data Setting data, or NULL to clear setting
105 * @v len Length of setting data
106 * @ret rc Return status code
107 */
108 int ( * store ) ( struct settings *settings,
109 const struct setting *setting,
110 const void *data, size_t len );
111 /** Fetch value of setting
112 *
113 * @v settings Settings block
114 * @v setting Setting to fetch
115 * @v data Buffer to fill with setting data
116 * @v len Length of buffer
117 * @ret len Length of setting data, or negative error
118 *
119 * The actual length of the setting will be returned even if
120 * the buffer was too small.
121 */
122 int ( * fetch ) ( struct settings *settings, struct setting *setting,
123 void *data, size_t len );
124 /** Clear settings block
125 *
126 * @v settings Settings block
127 */
128 void ( * clear ) ( struct settings *settings );
129 };
130
131 /** A settings block */
132 struct settings {
133 /** Reference counter */
134 struct refcnt *refcnt;
135 /** Name */
136 const char *name;
137 /** Parent settings block */
138 struct settings *parent;
139 /** Sibling settings blocks */
140 struct list_head siblings;
141 /** Child settings blocks */
142 struct list_head children;
143 /** Settings block operations */
144 struct settings_operations *op;
145 /** Default scope for numerical settings constructed for this block */
146 const struct settings_scope *default_scope;
147 /** Sibling ordering */
148 int order;
149 };
150
151 /**
152 * A setting scope
153 *
154 * Users can construct tags for settings that are not explicitly known
155 * to iPXE using the generic syntax for numerical settings. For
156 * example, the setting name "60" will be interpreted as referring to
157 * DHCP option 60 (the vendor class identifier).
158 *
159 * This creates a potential for namespace collisions, since the
160 * interpretation of the numerical description will vary according to
161 * the settings block. When a user attempts to fetch a generic
162 * numerical setting, we need to ensure that only the intended
163 * settings blocks interpret this numerical description. (For
164 * example, we do not want to attempt to retrieve the subnet mask from
165 * SMBIOS, or the system UUID from DHCP.)
166 *
167 * This potential problem is resolved by including a user-invisible
168 * "scope" within the definition of each setting. Settings blocks may
169 * use this to determine whether or not the setting is applicable.
170 * Any settings constructed from a numerical description
171 * (e.g. "smbios/1.4.0") will be assigned the default scope of the
172 * settings block specified in the description (e.g. "smbios"); this
173 * provides behaviour matching the user's expectations in most
174 * circumstances.
175 */
176 struct settings_scope {
177 /** Dummy field
178 *
179 * This is included only to ensure that pointers to different
180 * scopes always compare differently.
181 */
182 uint8_t dummy;
183 } __attribute__ (( packed ));
184
185 /**
186 * A setting type
187 *
188 * This represents a type of setting (e.g. string, IPv4 address,
189 * etc.).
190 */
191 struct setting_type {
192 /** Name
193 *
194 * This is the name exposed to the user (e.g. "string").
195 */
196 const char *name;
197 /** Parse formatted string to setting value
198 *
199 * @v type Setting type
200 * @v value Formatted setting value
201 * @v buf Buffer to contain raw value
202 * @v len Length of buffer
203 * @ret len Length of raw value, or negative error
204 */
205 int ( * parse ) ( const struct setting_type *type, const char *value,
206 void *buf, size_t len );
207 /** Format setting value as a string
208 *
209 * @v type Setting type
210 * @v raw Raw setting value
211 * @v raw_len Length of raw setting value
212 * @v buf Buffer to contain formatted value
213 * @v len Length of buffer
214 * @ret len Length of formatted value, or negative error
215 */
216 int ( * format ) ( const struct setting_type *type, const void *raw,
217 size_t raw_len, char *buf, size_t len );
218 /** Convert number to setting value
219 *
220 * @v type Setting type
221 * @v value Numeric value
222 * @v buf Buffer to contain raw value
223 * @v len Length of buffer
224 * @ret len Length of raw value, or negative error
225 */
226 int ( * denumerate ) ( const struct setting_type *type,
227 unsigned long value,
228 void *buf, size_t len );
229 /** Convert setting value to number
230 *
231 * @v type Setting type
232 * @v raw Raw setting value
233 * @v raw_len Length of raw setting value
234 * @v value Numeric value to fill in
235 * @ret rc Return status code
236 */
237 int ( * numerate ) ( const struct setting_type *type, const void *raw,
238 size_t raw_len, unsigned long *value );
239 };
240
241 /** Configuration setting type table */
242 #define SETTING_TYPES __table ( struct setting_type, "setting_types" )
243
244 /** Declare a configuration setting type */
245 #define __setting_type __table_entry ( SETTING_TYPES, 01 )
246
247 /**
248 * A settings applicator
249 *
250 */
251 struct settings_applicator {
252 /** Apply updated settings
253 *
254 * @ret rc Return status code
255 */
256 int ( * apply ) ( void );
257 };
258
259 /** Settings applicator table */
260 #define SETTINGS_APPLICATORS \
261 __table ( struct settings_applicator, "settings_applicators" )
262
263 /** Declare a settings applicator */
264 #define __settings_applicator __table_entry ( SETTINGS_APPLICATORS, 01 )
265
266 /** A built-in setting */
267 struct builtin_setting {
268 /** Setting */
269 const struct setting *setting;
270 /** Fetch setting value
271 *
272 * @v data Buffer to fill with setting data
273 * @v len Length of buffer
274 * @ret len Length of setting data, or negative error
275 */
276 int ( * fetch ) ( void *data, size_t len );
277 };
278
279 /** Built-in settings table */
280 #define BUILTIN_SETTINGS __table ( struct builtin_setting, "builtin_settings" )
281
282 /** Declare a built-in setting */
283 #define __builtin_setting __table_entry ( BUILTIN_SETTINGS, 01 )
284
285 /** Built-in setting scope */
286 extern const struct settings_scope builtin_scope;
287
288 /** IPv6 setting scope */
289 extern const struct settings_scope ipv6_settings_scope;
290
291 /** DHCPv6 setting scope */
292 extern const struct settings_scope dhcpv6_scope;
293
294 /**
295 * A generic settings block
296 *
297 */
298 struct generic_settings {
299 /** Settings block */
300 struct settings settings;
301 /** List of generic settings */
302 struct list_head list;
303 };
304
305 /** A child settings block locator function */
306 typedef struct settings * ( *get_child_settings_t ) ( struct settings *settings,
307 const char *name );
308 extern struct settings_operations generic_settings_operations;
309 extern int generic_settings_store ( struct settings *settings,
310 const struct setting *setting,
311 const void *data, size_t len );
312 extern int generic_settings_fetch ( struct settings *settings,
313 struct setting *setting,
314 void *data, size_t len );
315 extern void generic_settings_clear ( struct settings *settings );
316
317 extern int register_settings ( struct settings *settings,
318 struct settings *parent, const char *name );
319 extern void unregister_settings ( struct settings *settings );
320
321 extern struct settings * settings_target ( struct settings *settings );
322 extern int setting_applies ( struct settings *settings,
323 const struct setting *setting );
324 extern int store_setting ( struct settings *settings,
325 const struct setting *setting,
326 const void *data, size_t len );
327 extern int fetch_setting ( struct settings *settings,
328 const struct setting *setting,
329 struct settings **origin, struct setting *fetched,
330 void *data, size_t len );
331 extern int fetch_setting_copy ( struct settings *settings,
332 const struct setting *setting,
333 struct settings **origin,
334 struct setting *fetched, void **data );
335 extern int fetch_raw_setting ( struct settings *settings,
336 const struct setting *setting,
337 void *data, size_t len );
338 extern int fetch_raw_setting_copy ( struct settings *settings,
339 const struct setting *setting,
340 void **data );
341 extern int fetch_string_setting ( struct settings *settings,
342 const struct setting *setting,
343 char *data, size_t len );
344 extern int fetch_string_setting_copy ( struct settings *settings,
345 const struct setting *setting,
346 char **data );
347 extern int fetch_ipv4_array_setting ( struct settings *settings,
348 const struct setting *setting,
349 struct in_addr *inp, unsigned int count );
350 extern int fetch_ipv4_setting ( struct settings *settings,
351 const struct setting *setting,
352 struct in_addr *inp );
353 extern int fetch_ipv6_array_setting ( struct settings *settings,
354 const struct setting *setting,
355 struct in6_addr *inp, unsigned int count);
356 extern int fetch_ipv6_setting ( struct settings *settings,
357 const struct setting *setting,
358 struct in6_addr *inp );
359 extern int fetch_int_setting ( struct settings *settings,
360 const struct setting *setting, long *value );
361 extern int fetch_uint_setting ( struct settings *settings,
362 const struct setting *setting,
363 unsigned long *value );
364 extern long fetch_intz_setting ( struct settings *settings,
365 const struct setting *setting );
366 extern unsigned long fetch_uintz_setting ( struct settings *settings,
367 const struct setting *setting );
368 extern int fetch_uuid_setting ( struct settings *settings,
369 const struct setting *setting,
370 union uuid *uuid );
371 extern void clear_settings ( struct settings *settings );
372 extern int setting_cmp ( const struct setting *a, const struct setting *b );
373
374 extern struct settings * find_child_settings ( struct settings *parent,
375 const char *name );
376 extern struct settings * autovivify_child_settings ( struct settings *parent,
377 const char *name );
378 extern const char * settings_name ( struct settings *settings );
379 extern struct settings * find_settings ( const char *name );
380 extern struct setting * find_setting ( const char *name );
381 extern int parse_setting_name ( char *name, get_child_settings_t get_child,
382 struct settings **settings,
383 struct setting *setting );
384 extern int setting_name ( struct settings *settings,
385 const struct setting *setting,
386 char *buf, size_t len );
387 extern int setting_format ( const struct setting_type *type, const void *raw,
388 size_t raw_len, char *buf, size_t len );
389 extern int setting_parse ( const struct setting_type *type, const char *value,
390 void *buf, size_t len );
391 extern int setting_numerate ( const struct setting_type *type, const void *raw,
392 size_t raw_len, unsigned long *value );
393 extern int setting_denumerate ( const struct setting_type *type,
394 unsigned long value, void *buf, size_t len );
395 extern int fetchf_setting ( struct settings *settings,
396 const struct setting *setting,
397 struct settings **origin, struct setting *fetched,
398 char *buf, size_t len );
399 extern int fetchf_setting_copy ( struct settings *settings,
400 const struct setting *setting,
401 struct settings **origin,
402 struct setting *fetched, char **value );
403 extern int storef_setting ( struct settings *settings,
404 const struct setting *setting, const char *value );
405 extern int fetchn_setting ( struct settings *settings,
406 const struct setting *setting,
407 struct settings **origin, struct setting *fetched,
408 unsigned long *value );
409 extern int storen_setting ( struct settings *settings,
410 const struct setting *setting,
411 unsigned long value );
412 extern char * expand_settings ( const char *string );
413
414 extern const struct setting_type setting_type_string __setting_type;
415 extern const struct setting_type setting_type_uristring __setting_type;
416 extern const struct setting_type setting_type_ipv4 __setting_type;
417 extern const struct setting_type setting_type_ipv6 __setting_type;
418 extern const struct setting_type setting_type_int8 __setting_type;
419 extern const struct setting_type setting_type_int16 __setting_type;
420 extern const struct setting_type setting_type_int32 __setting_type;
421 extern const struct setting_type setting_type_uint8 __setting_type;
422 extern const struct setting_type setting_type_uint16 __setting_type;
423 extern const struct setting_type setting_type_uint32 __setting_type;
424 extern const struct setting_type setting_type_hex __setting_type;
425 extern const struct setting_type setting_type_hexhyp __setting_type;
426 extern const struct setting_type setting_type_hexraw __setting_type;
427 extern const struct setting_type setting_type_base64 __setting_type;
428 extern const struct setting_type setting_type_uuid __setting_type;
429 extern const struct setting_type setting_type_busdevfn __setting_type;
430 extern const struct setting_type setting_type_dnssl __setting_type;
431
432 extern const struct setting
433 ip_setting __setting ( SETTING_IP4, ip );
434 extern const struct setting
435 netmask_setting __setting ( SETTING_IP4, netmask );
436 extern const struct setting
437 gateway_setting __setting ( SETTING_IP4, gateway );
438 extern const struct setting
439 dns_setting __setting ( SETTING_IP4_EXTRA, dns );
440 extern const struct setting
441 ip6_setting __setting ( SETTING_IP6, ip6 );
442 extern const struct setting
443 len6_setting __setting ( SETTING_IP6, len6 );
444 extern const struct setting
445 gateway6_setting __setting ( SETTING_IP6, gateway6 );
446 extern const struct setting
447 hostname_setting __setting ( SETTING_HOST, hostname );
448 extern const struct setting
449 domain_setting __setting ( SETTING_IP_EXTRA, domain );
450 extern const struct setting
451 filename_setting __setting ( SETTING_BOOT, filename );
452 extern const struct setting
453 root_path_setting __setting ( SETTING_SANBOOT, root-path );
454 extern const struct setting
455 san_filename_setting __setting ( SETTING_SANBOOT, san-filename );
456 extern const struct setting
457 username_setting __setting ( SETTING_AUTH, username );
458 extern const struct setting
459 password_setting __setting ( SETTING_AUTH, password );
460 extern const struct setting
461 priority_setting __setting ( SETTING_MISC, priority );
462 extern const struct setting
463 uuid_setting __setting ( SETTING_HOST, uuid );
464 extern const struct setting
465 next_server_setting __setting ( SETTING_BOOT, next-server );
466 extern const struct setting
467 mac_setting __setting ( SETTING_NETDEV, mac );
468 extern const struct setting
469 busid_setting __setting ( SETTING_NETDEV, busid );
470 extern const struct setting
471 user_class_setting __setting ( SETTING_HOST_EXTRA, user-class );
472 extern const struct setting
473 vendor_class_setting __setting ( SETTING_HOST_EXTRA, vendor-class );
474 extern const struct setting
475 manufacturer_setting __setting ( SETTING_HOST_EXTRA, manufacturer );
476 extern const struct setting
477 product_setting __setting ( SETTING_HOST_EXTRA, product );
478 extern const struct setting
479 serial_setting __setting ( SETTING_HOST_EXTRA, serial );
480 extern const struct setting
481 asset_setting __setting ( SETTING_HOST_EXTRA, asset );
482 extern const struct setting
483 board_serial_setting __setting ( SETTING_HOST_EXTRA, board-serial );
484 extern const struct setting dhcp_server_setting __setting ( SETTING_MISC,
485 dhcp-server );
486
487 /**
488 * Initialise a settings block
489 *
490 * @v settings Settings block
491 * @v op Settings block operations
492 * @v refcnt Containing object reference counter, or NULL
493 * @v default_scope Default scope
494 */
settings_init(struct settings * settings,struct settings_operations * op,struct refcnt * refcnt,const struct settings_scope * default_scope)495 static inline void settings_init ( struct settings *settings,
496 struct settings_operations *op,
497 struct refcnt *refcnt,
498 const struct settings_scope *default_scope ){
499 INIT_LIST_HEAD ( &settings->siblings );
500 INIT_LIST_HEAD ( &settings->children );
501 settings->op = op;
502 settings->refcnt = refcnt;
503 settings->default_scope = default_scope;
504 }
505
506 /**
507 * Initialise a settings block
508 *
509 * @v generics Generic settings block
510 * @v refcnt Containing object reference counter, or NULL
511 */
generic_settings_init(struct generic_settings * generics,struct refcnt * refcnt)512 static inline void generic_settings_init ( struct generic_settings *generics,
513 struct refcnt *refcnt ) {
514 settings_init ( &generics->settings, &generic_settings_operations,
515 refcnt, NULL );
516 INIT_LIST_HEAD ( &generics->list );
517 }
518
519 /**
520 * Delete setting
521 *
522 * @v settings Settings block
523 * @v setting Setting to delete
524 * @ret rc Return status code
525 */
delete_setting(struct settings * settings,const struct setting * setting)526 static inline int delete_setting ( struct settings *settings,
527 const struct setting *setting ) {
528 return store_setting ( settings, setting, NULL, 0 );
529 }
530
531 /**
532 * Check existence of predefined setting
533 *
534 * @v settings Settings block, or NULL to search all blocks
535 * @v setting Setting to fetch
536 * @ret exists Setting exists
537 */
setting_exists(struct settings * settings,const struct setting * setting)538 static inline int setting_exists ( struct settings *settings,
539 const struct setting *setting ) {
540 return ( fetch_setting ( settings, setting, NULL, NULL,
541 NULL, 0 ) >= 0 );
542 }
543
544 #endif /* _IPXE_SETTINGS_H */
545