diff options
Diffstat (limited to 'qemu/roms/ipxe/src/include/ipxe/settings.h')
| -rw-r--r-- | qemu/roms/ipxe/src/include/ipxe/settings.h | 512 |
1 files changed, 512 insertions, 0 deletions
diff --git a/qemu/roms/ipxe/src/include/ipxe/settings.h b/qemu/roms/ipxe/src/include/ipxe/settings.h new file mode 100644 index 000000000..d6929ecd0 --- /dev/null +++ b/qemu/roms/ipxe/src/include/ipxe/settings.h @@ -0,0 +1,512 @@ +#ifndef _IPXE_SETTINGS_H +#define _IPXE_SETTINGS_H + +/** @file + * + * Configuration settings + * + */ + +FILE_LICENCE ( GPL2_OR_LATER ); + +#include <stdint.h> +#include <ipxe/tables.h> +#include <ipxe/list.h> +#include <ipxe/refcnt.h> + +struct settings; +struct in_addr; +struct in6_addr; +union uuid; + +/** A setting */ +struct setting { + /** Name + * + * This is the human-readable name for the setting. + */ + const char *name; + /** Description */ + const char *description; + /** Setting type + * + * This identifies the type of setting (e.g. string, IPv4 + * address, etc.). + */ + const struct setting_type *type; + /** Setting tag, if applicable + * + * The setting tag is a numerical description of the setting + * (such as a DHCP option number, or an SMBIOS structure and + * field number). + */ + unsigned int tag; + /** Setting scope (or NULL) + * + * For historic reasons, a NULL scope with a non-zero tag + * indicates a DHCPv4 option setting. + */ + const struct settings_scope *scope; +}; + +/** Configuration setting table */ +#define SETTINGS __table ( struct setting, "settings" ) + +/** Declare a configuration setting */ +#define __setting( setting_order, name ) \ + __table_entry ( SETTINGS, setting_order.name ) + +/** @defgroup setting_order Setting ordering + * @{ + */ + +#define SETTING_NETDEV 01 /**< Network device settings */ +#define SETTING_NETDEV_EXTRA 02 /**< Network device additional settings */ +#define SETTING_IP 03 /**< IPv4 settings */ +#define SETTING_IP_EXTRA 04 /**< IPv4 additional settings */ +#define SETTING_BOOT 05 /**< Generic boot settings */ +#define SETTING_BOOT_EXTRA 06 /**< Generic boot additional settings */ +#define SETTING_SANBOOT 07 /**< SAN boot settings */ +#define SETTING_SANBOOT_EXTRA 08 /**< SAN boot additional settings */ +#define SETTING_HOST 09 /**< Host identity settings */ +#define SETTING_HOST_EXTRA 10 /**< Host identity additional settings */ +#define SETTING_AUTH 11 /**< Authentication settings */ +#define SETTING_AUTH_EXTRA 12 /**< Authentication additional settings */ +#define SETTING_CRYPTO 13 /**< Cryptography settings */ +#define SETTING_MISC 14 /**< Miscellaneous settings */ + +/** @} */ + +/** Settings block operations */ +struct settings_operations { + /** Redirect to underlying settings block (if applicable) + * + * @v settings Settings block + * @ret settings Underlying settings block + */ + struct settings * ( * redirect ) ( struct settings *settings ); + /** Check applicability of setting + * + * @v settings Settings block + * @v setting Setting + * @ret applies Setting applies within this settings block + */ + int ( * applies ) ( struct settings *settings, + const struct setting *setting ); + /** Store value of setting + * + * @v settings Settings block + * @v setting Setting to store + * @v data Setting data, or NULL to clear setting + * @v len Length of setting data + * @ret rc Return status code + */ + int ( * store ) ( struct settings *settings, + const struct setting *setting, + const void *data, size_t len ); + /** Fetch value of setting + * + * @v settings Settings block + * @v setting Setting to fetch + * @v data Buffer to fill with setting data + * @v len Length of buffer + * @ret len Length of setting data, or negative error + * + * The actual length of the setting will be returned even if + * the buffer was too small. + */ + int ( * fetch ) ( struct settings *settings, struct setting *setting, + void *data, size_t len ); + /** Clear settings block + * + * @v settings Settings block + */ + void ( * clear ) ( struct settings *settings ); +}; + +/** A settings block */ +struct settings { + /** Reference counter */ + struct refcnt *refcnt; + /** Name */ + const char *name; + /** Parent settings block */ + struct settings *parent; + /** Sibling settings blocks */ + struct list_head siblings; + /** Child settings blocks */ + struct list_head children; + /** Settings block operations */ + struct settings_operations *op; + /** Default scope for numerical settings constructed for this block */ + const struct settings_scope *default_scope; +}; + +/** + * A setting scope + * + * Users can construct tags for settings that are not explicitly known + * to iPXE using the generic syntax for numerical settings. For + * example, the setting name "60" will be interpreted as referring to + * DHCP option 60 (the vendor class identifier). + * + * This creates a potential for namespace collisions, since the + * interpretation of the numerical description will vary according to + * the settings block. When a user attempts to fetch a generic + * numerical setting, we need to ensure that only the intended + * settings blocks interpret this numerical description. (For + * example, we do not want to attempt to retrieve the subnet mask from + * SMBIOS, or the system UUID from DHCP.) + * + * This potential problem is resolved by including a user-invisible + * "scope" within the definition of each setting. Settings blocks may + * use this to determine whether or not the setting is applicable. + * Any settings constructed from a numerical description + * (e.g. "smbios/1.4.0") will be assigned the default scope of the + * settings block specified in the description (e.g. "smbios"); this + * provides behaviour matching the user's expectations in most + * circumstances. + */ +struct settings_scope { + /** Dummy field + * + * This is included only to ensure that pointers to different + * scopes always compare differently. + */ + uint8_t dummy; +} __attribute__ (( packed )); + +/** + * A setting type + * + * This represents a type of setting (e.g. string, IPv4 address, + * etc.). + */ +struct setting_type { + /** Name + * + * This is the name exposed to the user (e.g. "string"). + */ + const char *name; + /** Parse formatted string to setting value + * + * @v type Setting type + * @v value Formatted setting value + * @v buf Buffer to contain raw value + * @v len Length of buffer + * @ret len Length of raw value, or negative error + */ + int ( * parse ) ( const struct setting_type *type, const char *value, + void *buf, size_t len ); + /** Format setting value as a string + * + * @v type Setting type + * @v raw Raw setting value + * @v raw_len Length of raw setting value + * @v buf Buffer to contain formatted value + * @v len Length of buffer + * @ret len Length of formatted value, or negative error + */ + int ( * format ) ( const struct setting_type *type, const void *raw, + size_t raw_len, char *buf, size_t len ); + /** Convert number to setting value + * + * @v type Setting type + * @v value Numeric value + * @v buf Buffer to contain raw value + * @v len Length of buffer + * @ret len Length of raw value, or negative error + */ + int ( * denumerate ) ( const struct setting_type *type, + unsigned long value, + void *buf, size_t len ); + /** Convert setting value to number + * + * @v type Setting type + * @v raw Raw setting value + * @v raw_len Length of raw setting value + * @v value Numeric value to fill in + * @ret rc Return status code + */ + int ( * numerate ) ( const struct setting_type *type, const void *raw, + size_t raw_len, unsigned long *value ); +}; + +/** Configuration setting type table */ +#define SETTING_TYPES __table ( struct setting_type, "setting_types" ) + +/** Declare a configuration setting type */ +#define __setting_type __table_entry ( SETTING_TYPES, 01 ) + +/** + * A settings applicator + * + */ +struct settings_applicator { + /** Apply updated settings + * + * @ret rc Return status code + */ + int ( * apply ) ( void ); +}; + +/** Settings applicator table */ +#define SETTINGS_APPLICATORS \ + __table ( struct settings_applicator, "settings_applicators" ) + +/** Declare a settings applicator */ +#define __settings_applicator __table_entry ( SETTINGS_APPLICATORS, 01 ) + +/** A built-in setting */ +struct builtin_setting { + /** Setting */ + const struct setting *setting; + /** Fetch setting value + * + * @v data Buffer to fill with setting data + * @v len Length of buffer + * @ret len Length of setting data, or negative error + */ + int ( * fetch ) ( void *data, size_t len ); +}; + +/** Built-in settings table */ +#define BUILTIN_SETTINGS __table ( struct builtin_setting, "builtin_settings" ) + +/** Declare a built-in setting */ +#define __builtin_setting __table_entry ( BUILTIN_SETTINGS, 01 ) + +/** Built-in setting scope */ +extern const struct settings_scope builtin_scope; + +/** IPv6 setting scope */ +extern const struct settings_scope ipv6_scope; + +/** + * A generic settings block + * + */ +struct generic_settings { + /** Settings block */ + struct settings settings; + /** List of generic settings */ + struct list_head list; +}; + +/** A child settings block locator function */ +typedef struct settings * ( *get_child_settings_t ) ( struct settings *settings, + const char *name ); +extern struct settings_operations generic_settings_operations; +extern int generic_settings_store ( struct settings *settings, + const struct setting *setting, + const void *data, size_t len ); +extern int generic_settings_fetch ( struct settings *settings, + struct setting *setting, + void *data, size_t len ); +extern void generic_settings_clear ( struct settings *settings ); + +extern int register_settings ( struct settings *settings, + struct settings *parent, const char *name ); +extern void unregister_settings ( struct settings *settings ); + +extern struct settings * settings_target ( struct settings *settings ); +extern int setting_applies ( struct settings *settings, + const struct setting *setting ); +extern int store_setting ( struct settings *settings, + const struct setting *setting, + const void *data, size_t len ); +extern int fetch_setting ( struct settings *settings, + const struct setting *setting, + struct settings **origin, struct setting *fetched, + void *data, size_t len ); +extern int fetch_setting_copy ( struct settings *settings, + const struct setting *setting, + struct settings **origin, + struct setting *fetched, void **data ); +extern int fetch_raw_setting ( struct settings *settings, + const struct setting *setting, + void *data, size_t len ); +extern int fetch_raw_setting_copy ( struct settings *settings, + const struct setting *setting, + void **data ); +extern int fetch_string_setting ( struct settings *settings, + const struct setting *setting, + char *data, size_t len ); +extern int fetch_string_setting_copy ( struct settings *settings, + const struct setting *setting, + char **data ); +extern int fetch_ipv4_array_setting ( struct settings *settings, + const struct setting *setting, + struct in_addr *inp, unsigned int count ); +extern int fetch_ipv4_setting ( struct settings *settings, + const struct setting *setting, + struct in_addr *inp ); +extern int fetch_ipv6_array_setting ( struct settings *settings, + const struct setting *setting, + struct in6_addr *inp, unsigned int count); +extern int fetch_ipv6_setting ( struct settings *settings, + const struct setting *setting, + struct in6_addr *inp ); +extern int fetch_int_setting ( struct settings *settings, + const struct setting *setting, long *value ); +extern int fetch_uint_setting ( struct settings *settings, + const struct setting *setting, + unsigned long *value ); +extern long fetch_intz_setting ( struct settings *settings, + const struct setting *setting ); +extern unsigned long fetch_uintz_setting ( struct settings *settings, + const struct setting *setting ); +extern int fetch_uuid_setting ( struct settings *settings, + const struct setting *setting, + union uuid *uuid ); +extern void clear_settings ( struct settings *settings ); +extern int setting_cmp ( const struct setting *a, const struct setting *b ); + +extern struct settings * find_child_settings ( struct settings *parent, + const char *name ); +extern struct settings * autovivify_child_settings ( struct settings *parent, + const char *name ); +extern const char * settings_name ( struct settings *settings ); +extern struct settings * find_settings ( const char *name ); +extern struct setting * find_setting ( const char *name ); +extern int parse_setting_name ( char *name, get_child_settings_t get_child, + struct settings **settings, + struct setting *setting ); +extern int setting_name ( struct settings *settings, + const struct setting *setting, + char *buf, size_t len ); +extern int setting_format ( const struct setting_type *type, const void *raw, + size_t raw_len, char *buf, size_t len ); +extern int setting_parse ( const struct setting_type *type, const char *value, + void *buf, size_t len ); +extern int setting_numerate ( const struct setting_type *type, const void *raw, + size_t raw_len, unsigned long *value ); +extern int setting_denumerate ( const struct setting_type *type, + unsigned long value, void *buf, size_t len ); +extern int fetchf_setting ( struct settings *settings, + const struct setting *setting, + struct settings **origin, struct setting *fetched, + char *buf, size_t len ); +extern int fetchf_setting_copy ( struct settings *settings, + const struct setting *setting, + struct settings **origin, + struct setting *fetched, char **value ); +extern int storef_setting ( struct settings *settings, + const struct setting *setting, const char *value ); +extern int fetchn_setting ( struct settings *settings, + const struct setting *setting, + struct settings **origin, struct setting *fetched, + unsigned long *value ); +extern int storen_setting ( struct settings *settings, + const struct setting *setting, + unsigned long value ); +extern char * expand_settings ( const char *string ); + +extern const struct setting_type setting_type_string __setting_type; +extern const struct setting_type setting_type_uristring __setting_type; +extern const struct setting_type setting_type_ipv4 __setting_type; +extern const struct setting_type setting_type_ipv6 __setting_type; +extern const struct setting_type setting_type_int8 __setting_type; +extern const struct setting_type setting_type_int16 __setting_type; +extern const struct setting_type setting_type_int32 __setting_type; +extern const struct setting_type setting_type_uint8 __setting_type; +extern const struct setting_type setting_type_uint16 __setting_type; +extern const struct setting_type setting_type_uint32 __setting_type; +extern const struct setting_type setting_type_hex __setting_type; +extern const struct setting_type setting_type_hexhyp __setting_type; +extern const struct setting_type setting_type_hexraw __setting_type; +extern const struct setting_type setting_type_uuid __setting_type; +extern const struct setting_type setting_type_busdevfn __setting_type; +extern const struct setting_type setting_type_dnssl __setting_type; + +extern const struct setting +ip_setting __setting ( SETTING_IP, ip ); +extern const struct setting +netmask_setting __setting ( SETTING_IP, netmask ); +extern const struct setting +gateway_setting __setting ( SETTING_IP, gateway ); +extern const struct setting +dns_setting __setting ( SETTING_IP_EXTRA, dns ); +extern const struct setting +hostname_setting __setting ( SETTING_HOST, hostname ); +extern const struct setting +domain_setting __setting ( SETTING_IP_EXTRA, domain ); +extern const struct setting +filename_setting __setting ( SETTING_BOOT, filename ); +extern const struct setting +root_path_setting __setting ( SETTING_SANBOOT, root-path ); +extern const struct setting +username_setting __setting ( SETTING_AUTH, username ); +extern const struct setting +password_setting __setting ( SETTING_AUTH, password ); +extern const struct setting +priority_setting __setting ( SETTING_MISC, priority ); +extern const struct setting +uuid_setting __setting ( SETTING_HOST, uuid ); +extern const struct setting +next_server_setting __setting ( SETTING_BOOT, next-server ); +extern const struct setting +mac_setting __setting ( SETTING_NETDEV, mac ); +extern const struct setting +busid_setting __setting ( SETTING_NETDEV, busid ); +extern const struct setting +user_class_setting __setting ( SETTING_HOST_EXTRA, user-class ); + +/** + * Initialise a settings block + * + * @v settings Settings block + * @v op Settings block operations + * @v refcnt Containing object reference counter, or NULL + * @v default_scope Default scope + */ +static inline void settings_init ( struct settings *settings, + struct settings_operations *op, + struct refcnt *refcnt, + const struct settings_scope *default_scope ){ + INIT_LIST_HEAD ( &settings->siblings ); + INIT_LIST_HEAD ( &settings->children ); + settings->op = op; + settings->refcnt = refcnt; + settings->default_scope = default_scope; +} + +/** + * Initialise a settings block + * + * @v generics Generic settings block + * @v refcnt Containing object reference counter, or NULL + */ +static inline void generic_settings_init ( struct generic_settings *generics, + struct refcnt *refcnt ) { + settings_init ( &generics->settings, &generic_settings_operations, + refcnt, NULL ); + INIT_LIST_HEAD ( &generics->list ); +} + +/** + * Delete setting + * + * @v settings Settings block + * @v setting Setting to delete + * @ret rc Return status code + */ +static inline int delete_setting ( struct settings *settings, + const struct setting *setting ) { + return store_setting ( settings, setting, NULL, 0 ); +} + +/** + * Check existence of predefined setting + * + * @v settings Settings block, or NULL to search all blocks + * @v setting Setting to fetch + * @ret exists Setting exists + */ +static inline int setting_exists ( struct settings *settings, + const struct setting *setting ) { + return ( fetch_setting ( settings, setting, NULL, NULL, + NULL, 0 ) >= 0 ); +} + +#endif /* _IPXE_SETTINGS_H */ |