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