#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;
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.).
*/
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.
*/
struct settings_scope *scope;
};
/** Configuration setting table */
#define SETTINGS __table ( struct setting, "settings" )
/** Declare a configuration setting */
#define __setting( setting_order ) __table_entry ( SETTINGS, setting_order )
/** @defgroup setting_order Setting ordering
* @{
*/
#define SETTING_NETDEV 01 /**< Network device settings */
#define SETTING_NETDEV_EXTRA 02 /**< Network device additional settings */
#define SETTING_IPv4 03 /**< IPv4 settings */
#define SETTING_IPv4_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,
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, 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 */
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 setting value
*
* @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 char *value, void *buf, size_t len );
/** Format setting value
*
* @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 void *raw, size_t raw_len, char *buf,
size_t len );
};
/** 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 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,
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,
struct setting *setting );
extern int store_setting ( struct settings *settings, struct setting *setting,
const void *data, size_t len );
extern int fetch_setting ( struct settings *settings, struct setting *setting,
void *data, size_t len );
extern struct settings * fetch_setting_origin ( struct settings *settings,
struct setting *setting );
extern int fetch_setting_len ( struct settings *settings,
struct setting *setting );
extern int fetch_setting_copy ( struct settings *settings,
struct setting *setting, void **data );
extern int fetch_string_setting ( struct settings *settings,
struct setting *setting,
char *data, size_t len );
extern int fetch_string_setting_copy ( struct settings *settings,
struct setting *setting,
char **data );
extern int fetch_ipv4_array_setting ( struct settings *settings,
struct setting *setting,
struct in_addr *inp,
unsigned int count );
extern int fetch_ipv4_setting ( struct settings *settings,
struct setting *setting, struct in_addr *inp );
extern int fetch_int_setting ( struct settings *settings,
struct setting *setting, long *value );
extern int fetch_uint_setting ( struct settings *settings,
struct setting *setting,
unsigned long *value );
extern long fetch_intz_setting ( struct settings *settings,
struct setting *setting );
extern unsigned long fetch_uintz_setting ( struct settings *settings,
struct setting *setting );
extern int fetch_uuid_setting ( struct settings *settings,
struct setting *setting, union uuid *uuid );
extern void clear_settings ( struct settings *settings );
extern int setting_cmp ( struct setting *a, 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, struct setting *setting,
char *buf, size_t len );
extern int fetchf_setting ( struct settings *settings, struct setting *setting,
char *buf, size_t len );
extern int fetchf_setting_copy ( struct settings *settings,
struct setting *setting, char **value );
extern int storef_setting ( struct settings *settings,
struct setting *setting,
const char *value );
extern char * expand_settings ( const char *string );
extern struct setting_type setting_type_string __setting_type;
extern struct setting_type setting_type_uristring __setting_type;
extern struct setting_type setting_type_ipv4 __setting_type;
extern struct setting_type setting_type_int8 __setting_type;
extern struct setting_type setting_type_int16 __setting_type;
extern struct setting_type setting_type_int32 __setting_type;
extern struct setting_type setting_type_uint8 __setting_type;
extern struct setting_type setting_type_uint16 __setting_type;
extern struct setting_type setting_type_uint32 __setting_type;
extern struct setting_type setting_type_hex __setting_type;
extern struct setting_type setting_type_hexhyp __setting_type;
extern struct setting_type setting_type_hexraw __setting_type;
extern struct setting_type setting_type_uuid __setting_type;
extern struct setting_type setting_type_busdevfn __setting_type;
extern struct setting ip_setting __setting ( SETTING_IPv4 );
extern struct setting netmask_setting __setting ( SETTING_IPv4 );
extern struct setting gateway_setting __setting ( SETTING_IPv4 );
extern struct setting dns_setting __setting ( SETTING_IPv4_EXTRA );
extern struct setting hostname_setting __setting ( SETTING_HOST );
extern struct setting domain_setting __setting ( SETTING_IPv4_EXTRA );
extern struct setting filename_setting __setting ( SETTING_BOOT );
extern struct setting root_path_setting __setting ( SETTING_SANBOOT );
extern struct setting username_setting __setting ( SETTING_AUTH );
extern struct setting password_setting __setting ( SETTING_AUTH );
extern struct setting priority_setting __setting ( SETTING_MISC );
extern struct setting uuid_setting __setting ( SETTING_HOST );
extern struct setting next_server_setting __setting ( SETTING_BOOT );
extern struct setting mac_setting __setting ( SETTING_NETDEV );
extern struct setting busid_setting __setting ( SETTING_NETDEV );
/**
* 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,
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,
struct setting *setting ) {
return store_setting ( settings, setting, NULL, 0 );
}
/**
* Check existence of 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,
struct setting *setting ) {
return ( fetch_setting_len ( settings, setting ) >= 0 );
}
#endif /* _IPXE_SETTINGS_H */
