qemu/roms/ipxe/src/include/ipxe/settings.h

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