src/include/gpxe/settings.h

   1 #ifndef _GPXE_SETTINGS_H
   2 #define _GPXE_SETTINGS_H
   3
   4 /** @file
   5  *
   6  * Configuration settings
   7  *
   8  */
   9
  10 #include <stdint.h>
  11 #include <gpxe/tables.h>
  12 #include <gpxe/list.h>
  13 #include <gpxe/refcnt.h>
  14 #include <gpxe/dhcpopts.h>
  15
  16 struct settings;
  17 struct in_addr;
  18 union uuid;
  19
  20 /** A setting */
  21 struct setting {
  22         /** Name
  23          *
  24          * This is the human-readable name for the setting.
  25          */
  26         const char *name;
  27         /** Description */
  28         const char *description;
  29         /** Setting type
  30          *
  31          * This identifies the type of setting (e.g. string, IPv4
  32          * address, etc.).
  33          */
  34         struct setting_type *type;
  35         /** DHCP option number, if applicable */
  36         unsigned int tag;
  37 };
  38
  39 /** Configuration setting table */
  40 #define SETTINGS __table ( struct setting, "settings" )
  41
  42 /** Declare a configuration setting */
  43 #define __setting __table_entry ( SETTINGS, 01 )
  44
  45 /** Settings block operations */
  46 struct settings_operations {
  47         /** Store value of setting
  48          *
  49          * @v settings          Settings block
  50          * @v setting           Setting to store
  51          * @v data              Setting data, or NULL to clear setting
  52          * @v len               Length of setting data
  53          * @ret rc              Return status code
  54          */
  55         int ( * store ) ( struct settings *settings, struct setting *setting,
  56                           const void *data, size_t len );
  57         /** Fetch value of setting
  58          *
  59          * @v settings          Settings block
  60          * @v setting           Setting to fetch
  61          * @v data              Buffer to fill with setting data
  62          * @v len               Length of buffer
  63          * @ret len             Length of setting data, or negative error
  64          *
  65          * The actual length of the setting will be returned even if
  66          * the buffer was too small.
  67          */
  68         int ( * fetch ) ( struct settings *settings, struct setting *setting,
  69                           void *data, size_t len );
  70 };
  71
  72 /** A settings block */
  73 struct settings {
  74         /** Reference counter */
  75         struct refcnt *refcnt;
  76         /** Name */
  77         const char *name;
  78         /** Tag magic
  79          *
  80          * This value will be ORed in to any numerical tags
  81          * constructed by parse_setting_name(), and can be used to
  82          * avoid e.g. attempting to retrieve the subnet mask from
  83          * SMBIOS, or the system UUID from DHCP.
  84          */
  85         unsigned int tag_magic;
  86         /** Parent settings block */
  87         struct settings *parent;
  88         /** Sibling settings blocks */
  89         struct list_head siblings;
  90         /** Child settings blocks */
  91         struct list_head children;
  92         /** Settings block operations */
  93         struct settings_operations *op;
  94 };
  95
  96 /**
  97  * A setting type
  98  *
  99  * This represents a type of setting (e.g. string, IPv4 address,
 100  * etc.).
 101  */
 102 struct setting_type {
 103         /** Name
 104          *
 105          * This is the name exposed to the user (e.g. "string").
 106          */
 107         const char *name;
 108         /** Parse and set value of setting
 109          *
 110          * @v settings          Settings block
 111          * @v setting           Setting to store
 112          * @v value             Formatted setting data
 113          * @ret rc              Return status code
 114          */
 115         int ( * storef ) ( struct settings *settings, struct setting *setting,
 116                            const char *value );
 117         /** Fetch and format value of setting
 118          *
 119          * @v settings          Settings block
 120          * @v setting           Setting to fetch
 121          * @v buf               Buffer to contain formatted value
 122          * @v len               Length of buffer
 123          * @ret len             Length of formatted value, or negative error
 124          */
 125         int ( * fetchf ) ( struct settings *settings, struct setting *setting,
 126                            char *buf, size_t len );
 127 };
 128
 129 /** Configuration setting type table */
 130 #define SETTING_TYPES __table ( struct setting_type, "setting_types" )
 131
 132 /** Declare a configuration setting type */
 133 #define __setting_type __table_entry ( SETTING_TYPES, 01 )
 134
 135 /**
 136  * A settings applicator
 137  *
 138  */
 139 struct settings_applicator {
 140         /** Apply updated settings
 141          *
 142          * @ret rc              Return status code
 143          */
 144         int ( * apply ) ( void );
 145 };
 146
 147 /** Settings applicator table */
 148 #define SETTINGS_APPLICATORS \
 149         __table ( struct settings_applicator, "settings_applicators" )
 150
 151 /** Declare a settings applicator */
 152 #define __settings_applicator __table_entry ( SETTINGS_APPLICATORS, 01 )
 153
 154 /**
 155  * A simple settings block
 156  *
 157  */
 158 struct simple_settings {
 159         /** Settings block */
 160         struct settings settings;
 161         /** DHCP options */
 162         struct dhcp_options dhcpopts;
 163 };
 164
 165 extern struct settings_operations simple_settings_operations;
 166 extern int simple_settings_store ( struct settings *settings,
 167                                    struct setting *setting,
 168                                    const void *data, size_t len );
 169 extern int simple_settings_fetch ( struct settings *settings,
 170                                    struct setting *setting,
 171                                    void *data, size_t len );
 172
 173 extern int register_settings ( struct settings *settings,
 174                                struct settings *parent );
 175 extern void unregister_settings ( struct settings *settings );
 176
 177 extern int store_setting ( struct settings *settings, struct setting *setting,
 178                            const void *data, size_t len );
 179 extern int fetch_setting ( struct settings *settings, struct setting *setting,
 180                            void *data, size_t len );
 181 extern int fetch_setting_len ( struct settings *settings,
 182                                struct setting *setting );
 183 extern int fetch_string_setting ( struct settings *settings,
 184                                   struct setting *setting,
 185                                   char *data, size_t len );
 186 extern int fetch_string_setting_copy ( struct settings *settings,
 187                                        struct setting *setting,
 188                                        char **data );
 189 extern int fetch_ipv4_setting ( struct settings *settings,
 190                                 struct setting *setting, struct in_addr *inp );
 191 extern int fetch_int_setting ( struct settings *settings,
 192                                struct setting *setting, long *value );
 193 extern int fetch_uint_setting ( struct settings *settings,
 194                                 struct setting *setting,
 195                                 unsigned long *value );
 196 extern long fetch_intz_setting ( struct settings *settings,
 197                                  struct setting *setting );
 198 extern unsigned long fetch_uintz_setting ( struct settings *settings,
 199                                            struct setting *setting );
 200 extern int fetch_uuid_setting ( struct settings *settings,
 201                                 struct setting *setting, union uuid *uuid );
 202 extern int setting_cmp ( struct setting *a, struct setting *b );
 203
 204 extern struct settings * find_settings ( const char *name );
 205
 206 extern int storef_setting ( struct settings *settings,
 207                             struct setting *setting,
 208                             const char *value );
 209 extern int storef_named_setting ( const char *name, const char *value );
 210 extern int fetchf_named_setting ( const char *name, char *buf, size_t len );
 211
 212 extern struct setting_type setting_type_string __setting_type;
 213 extern struct setting_type setting_type_ipv4 __setting_type;
 214 extern struct setting_type setting_type_int8 __setting_type;
 215 extern struct setting_type setting_type_int16 __setting_type;
 216 extern struct setting_type setting_type_int32 __setting_type;
 217 extern struct setting_type setting_type_uint8 __setting_type;
 218 extern struct setting_type setting_type_uint16 __setting_type;
 219 extern struct setting_type setting_type_uint32 __setting_type;
 220 extern struct setting_type setting_type_hex __setting_type;
 221 extern struct setting_type setting_type_uuid __setting_type;
 222
 223 extern struct setting ip_setting __setting;
 224 extern struct setting netmask_setting __setting;
 225 extern struct setting gateway_setting __setting;
 226 extern struct setting dns_setting __setting;
 227 extern struct setting domain_setting __setting;
 228 extern struct setting hostname_setting __setting;
 229 extern struct setting filename_setting __setting;
 230 extern struct setting root_path_setting __setting;
 231 extern struct setting username_setting __setting;
 232 extern struct setting password_setting __setting;
 233 extern struct setting priority_setting __setting;
 234 extern struct setting uuid_setting __setting;
 235 extern struct setting next_server_setting __setting;
 236 extern struct setting mac_setting __setting;
 237 extern struct setting user_class_setting __setting;
 238
 239 /**
 240  * Initialise a settings block
 241  *
 242  * @v settings          Settings block
 243  * @v op                Settings block operations
 244  * @v refcnt            Containing object reference counter, or NULL
 245  * @v name              Settings block name
 246  * @v tag_magic         Tag magic
 247  */
 248 static inline void settings_init ( struct settings *settings,
 249                                    struct settings_operations *op,
 250                                    struct refcnt *refcnt,
 251                                    const char *name,
 252                                    unsigned int tag_magic ) {
 253         INIT_LIST_HEAD ( &settings->siblings );
 254         INIT_LIST_HEAD ( &settings->children );
 255         settings->op = op;
 256         settings->refcnt = refcnt;
 257         settings->name = name;
 258         settings->tag_magic = tag_magic;
 259 }
 260
 261 /**
 262  * Initialise a settings block
 263  *
 264  * @v simple            Simple settings block
 265  * @v refcnt            Containing object reference counter, or NULL
 266  * @v name              Settings block name
 267  */
 268 static inline void simple_settings_init ( struct simple_settings *simple,
 269                                           struct refcnt *refcnt,
 270                                           const char *name ) {
 271         settings_init ( &simple->settings, &simple_settings_operations,
 272                         refcnt, name, 0 );
 273 }
 274
 275 /**
 276  * Delete setting
 277  *
 278  * @v settings          Settings block
 279  * @v setting           Setting to delete
 280  * @ret rc              Return status code
 281  */
 282 static inline int delete_setting ( struct settings *settings,
 283                                    struct setting *setting ) {
 284         return store_setting ( settings, setting, NULL, 0 );
 285 }
 286
 287 /**
 288  * Fetch and format value of setting
 289  *
 290  * @v settings          Settings block, or NULL to search all blocks
 291  * @v setting           Setting to fetch
 292  * @v type              Settings type
 293  * @v buf               Buffer to contain formatted value
 294  * @v len               Length of buffer
 295  * @ret len             Length of formatted value, or negative error
 296  */
 297 static inline int fetchf_setting ( struct settings *settings,
 298                                    struct setting *setting,
 299                                    char *buf, size_t len ) {
 300         return setting->type->fetchf ( settings, setting, buf, len );
 301 }
 302
 303 /**
 304  * Delete named setting
 305  *
 306  * @v name              Name of setting
 307  * @ret rc              Return status code
 308  */
 309 static inline int delete_named_setting ( const char *name ) {
 310         return storef_named_setting ( name, NULL );
 311 }
 312
 313 /**
 314  * Check existence of setting
 315  *
 316  * @v settings          Settings block, or NULL to search all blocks
 317  * @v setting           Setting to fetch
 318  * @ret exists          Setting exists
 319  */
 320 static inline int setting_exists ( struct settings *settings,
 321                                    struct setting *setting ) {
 322         return ( fetch_setting_len ( settings, setting ) >= 0 );
 323 }
 324
 325 #endif /* _GPXE_SETTINGS_H */