iPXE
settings.h
Go to the documentation of this file.
00001 #ifndef _IPXE_SETTINGS_H
00002 #define _IPXE_SETTINGS_H
00003 
00004 /** @file
00005  *
00006  * Configuration settings
00007  *
00008  */
00009 
00010 FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
00011 
00012 #include <stdint.h>
00013 #include <ipxe/tables.h>
00014 #include <ipxe/list.h>
00015 #include <ipxe/refcnt.h>
00016 
00017 struct settings;
00018 struct in_addr;
00019 struct in6_addr;
00020 union uuid;
00021 
00022 /** A setting */
00023 struct setting {
00024         /** Name
00025          *
00026          * This is the human-readable name for the setting.
00027          */
00028         const char *name;
00029         /** Description */
00030         const char *description;
00031         /** Setting type
00032          *
00033          * This identifies the type of setting (e.g. string, IPv4
00034          * address, etc.).
00035          */
00036         const struct setting_type *type;
00037         /** Setting tag, if applicable
00038          *
00039          * The setting tag is a numerical description of the setting
00040          * (such as a DHCP option number, or an SMBIOS structure and
00041          * field number).
00042          */
00043         uint64_t tag;
00044         /** Setting scope (or NULL)
00045          *
00046          * For historic reasons, a NULL scope with a non-zero tag
00047          * indicates a DHCPv4 option setting.
00048          */
00049         const struct settings_scope *scope;
00050 };
00051 
00052 /** Configuration setting table */
00053 #define SETTINGS __table ( struct setting, "settings" )
00054 
00055 /** Declare a configuration setting */
00056 #define __setting( setting_order, name ) \
00057         __table_entry ( SETTINGS, setting_order.name )
00058 
00059 /** @defgroup setting_order Setting ordering
00060  * @{
00061  */
00062 
00063 #define SETTING_NETDEV          01 /**< Network device settings */
00064 #define SETTING_NETDEV_EXTRA    02 /**< Network device additional settings */
00065 #define SETTING_IP4             03 /**< IPv4 settings */
00066 #define SETTING_IP4_EXTRA       04 /**< IPv4 additional settings */
00067 #define SETTING_IP6             05 /**< IPv6 settings */
00068 #define SETTING_IP6_EXTRA       06 /**< IPv6 additional settings */
00069 #define SETTING_IP              07 /**< IPv4 settings */
00070 #define SETTING_IP_EXTRA        08 /**< IPv4 additional settings */
00071 #define SETTING_BOOT            09 /**< Generic boot settings */
00072 #define SETTING_BOOT_EXTRA      10 /**< Generic boot additional settings */
00073 #define SETTING_SANBOOT         11 /**< SAN boot settings */
00074 #define SETTING_SANBOOT_EXTRA   12 /**< SAN boot additional settings */
00075 #define SETTING_HOST            13 /**< Host identity settings */
00076 #define SETTING_HOST_EXTRA      14 /**< Host identity additional settings */
00077 #define SETTING_AUTH            15 /**< Authentication settings */
00078 #define SETTING_AUTH_EXTRA      16 /**< Authentication additional settings */
00079 #define SETTING_CRYPTO          17 /**< Cryptography settings */
00080 #define SETTING_MISC            18 /**< Miscellaneous settings */
00081 
00082 /** @} */
00083 
00084 /** Settings block operations */
00085 struct settings_operations {
00086         /** Redirect to underlying settings block (if applicable)
00087          *
00088          * @v settings          Settings block
00089          * @ret settings        Underlying settings block
00090          */
00091         struct settings * ( * redirect ) ( struct settings *settings );
00092         /** Check applicability of setting
00093          *
00094          * @v settings          Settings block
00095          * @v setting           Setting
00096          * @ret applies         Setting applies within this settings block
00097          */
00098         int ( * applies ) ( struct settings *settings,
00099                             const struct setting *setting );
00100         /** Store value of setting
00101          *
00102          * @v settings          Settings block
00103          * @v setting           Setting to store
00104          * @v data              Setting data, or NULL to clear setting
00105          * @v len               Length of setting data
00106          * @ret rc              Return status code
00107          */
00108         int ( * store ) ( struct settings *settings,
00109                           const struct setting *setting,
00110                           const void *data, size_t len );
00111         /** Fetch value of setting
00112          *
00113          * @v settings          Settings block
00114          * @v setting           Setting to fetch
00115          * @v data              Buffer to fill with setting data
00116          * @v len               Length of buffer
00117          * @ret len             Length of setting data, or negative error
00118          *
00119          * The actual length of the setting will be returned even if
00120          * the buffer was too small.
00121          */
00122         int ( * fetch ) ( struct settings *settings, struct setting *setting,
00123                           void *data, size_t len );
00124         /** Clear settings block
00125          *
00126          * @v settings          Settings block
00127          */
00128         void ( * clear ) ( struct settings *settings );
00129 };
00130 
00131 /** A settings block */
00132 struct settings {
00133         /** Reference counter */
00134         struct refcnt *refcnt;
00135         /** Name */
00136         const char *name;
00137         /** Parent settings block */
00138         struct settings *parent;
00139         /** Sibling settings blocks */
00140         struct list_head siblings;
00141         /** Child settings blocks */
00142         struct list_head children;
00143         /** Settings block operations */
00144         struct settings_operations *op;
00145         /** Default scope for numerical settings constructed for this block */
00146         const struct settings_scope *default_scope;
00147         /** Sibling ordering */
00148         int order;
00149 };
00150 
00151 /**
00152  * A setting scope
00153  *
00154  * Users can construct tags for settings that are not explicitly known
00155  * to iPXE using the generic syntax for numerical settings.  For
00156  * example, the setting name "60" will be interpreted as referring to
00157  * DHCP option 60 (the vendor class identifier).
00158  *
00159  * This creates a potential for namespace collisions, since the
00160  * interpretation of the numerical description will vary according to
00161  * the settings block.  When a user attempts to fetch a generic
00162  * numerical setting, we need to ensure that only the intended
00163  * settings blocks interpret this numerical description.  (For
00164  * example, we do not want to attempt to retrieve the subnet mask from
00165  * SMBIOS, or the system UUID from DHCP.)
00166  *
00167  * This potential problem is resolved by including a user-invisible
00168  * "scope" within the definition of each setting.  Settings blocks may
00169  * use this to determine whether or not the setting is applicable.
00170  * Any settings constructed from a numerical description
00171  * (e.g. "smbios/1.4.0") will be assigned the default scope of the
00172  * settings block specified in the description (e.g. "smbios"); this
00173  * provides behaviour matching the user's expectations in most
00174  * circumstances.
00175  */
00176 struct settings_scope {
00177         /** Dummy field
00178          *
00179          * This is included only to ensure that pointers to different
00180          * scopes always compare differently.
00181          */
00182         uint8_t dummy;
00183 } __attribute__ (( packed ));
00184 
00185 /**
00186  * A setting type
00187  *
00188  * This represents a type of setting (e.g. string, IPv4 address,
00189  * etc.).
00190  */
00191 struct setting_type {
00192         /** Name
00193          *
00194          * This is the name exposed to the user (e.g. "string").
00195          */
00196         const char *name;
00197         /** Parse formatted string to setting value
00198          *
00199          * @v type              Setting type
00200          * @v value             Formatted setting value
00201          * @v buf               Buffer to contain raw value
00202          * @v len               Length of buffer
00203          * @ret len             Length of raw value, or negative error
00204          */
00205         int ( * parse ) ( const struct setting_type *type, const char *value,
00206                           void *buf, size_t len );
00207         /** Format setting value as a string
00208          *
00209          * @v type              Setting type
00210          * @v raw               Raw setting value
00211          * @v raw_len           Length of raw setting value
00212          * @v buf               Buffer to contain formatted value
00213          * @v len               Length of buffer
00214          * @ret len             Length of formatted value, or negative error
00215          */
00216         int ( * format ) ( const struct setting_type *type, const void *raw,
00217                            size_t raw_len, char *buf, size_t len );
00218         /** Convert number to setting value
00219          *
00220          * @v type              Setting type
00221          * @v value             Numeric value
00222          * @v buf               Buffer to contain raw value
00223          * @v len               Length of buffer
00224          * @ret len             Length of raw value, or negative error
00225          */
00226         int ( * denumerate ) ( const struct setting_type *type,
00227                                unsigned long value,
00228                                void *buf, size_t len );
00229         /** Convert setting value to number
00230          *
00231          * @v type              Setting type
00232          * @v raw               Raw setting value
00233          * @v raw_len           Length of raw setting value
00234          * @v value             Numeric value to fill in
00235          * @ret rc              Return status code
00236          */
00237         int ( * numerate ) ( const struct setting_type *type, const void *raw,
00238                              size_t raw_len, unsigned long *value );
00239 };
00240 
00241 /** Configuration setting type table */
00242 #define SETTING_TYPES __table ( struct setting_type, "setting_types" )
00243 
00244 /** Declare a configuration setting type */
00245 #define __setting_type __table_entry ( SETTING_TYPES, 01 )
00246 
00247 /**
00248  * A settings applicator
00249  *
00250  */
00251 struct settings_applicator {
00252         /** Apply updated settings
00253          *
00254          * @ret rc              Return status code
00255          */
00256         int ( * apply ) ( void );
00257 };
00258 
00259 /** Settings applicator table */
00260 #define SETTINGS_APPLICATORS \
00261         __table ( struct settings_applicator, "settings_applicators" )
00262 
00263 /** Declare a settings applicator */
00264 #define __settings_applicator __table_entry ( SETTINGS_APPLICATORS, 01 )
00265 
00266 /** A built-in setting */
00267 struct builtin_setting {
00268         /** Setting */
00269         const struct setting *setting;
00270         /** Fetch setting value
00271          *
00272          * @v data              Buffer to fill with setting data
00273          * @v len               Length of buffer
00274          * @ret len             Length of setting data, or negative error
00275          */
00276         int ( * fetch ) ( void *data, size_t len );
00277 };
00278 
00279 /** Built-in settings table */
00280 #define BUILTIN_SETTINGS __table ( struct builtin_setting, "builtin_settings" )
00281 
00282 /** Declare a built-in setting */
00283 #define __builtin_setting __table_entry ( BUILTIN_SETTINGS, 01 )
00284 
00285 /** Built-in setting scope */
00286 extern const struct settings_scope builtin_scope;
00287 
00288 /** IPv6 setting scope */
00289 extern const struct settings_scope ipv6_settings_scope;
00290 
00291 /** DHCPv6 setting scope */
00292 extern const struct settings_scope dhcpv6_scope;
00293 
00294 /**
00295  * A generic settings block
00296  *
00297  */
00298 struct generic_settings {
00299         /** Settings block */
00300         struct settings settings;
00301         /** List of generic settings */
00302         struct list_head list;
00303 };
00304 
00305 /** A child settings block locator function */
00306 typedef struct settings * ( *get_child_settings_t ) ( struct settings *settings,
00307                                                       const char *name );
00308 extern struct settings_operations generic_settings_operations;
00309 extern int generic_settings_store ( struct settings *settings,
00310                                     const struct setting *setting,
00311                                     const void *data, size_t len );
00312 extern int generic_settings_fetch ( struct settings *settings,
00313                                     struct setting *setting,
00314                                     void *data, size_t len );
00315 extern void generic_settings_clear ( struct settings *settings );
00316 
00317 extern int register_settings ( struct settings *settings,
00318                                struct settings *parent, const char *name );
00319 extern void unregister_settings ( struct settings *settings );
00320 
00321 extern struct settings * settings_target ( struct settings *settings );
00322 extern int setting_applies ( struct settings *settings,
00323                              const struct setting *setting );
00324 extern int store_setting ( struct settings *settings,
00325                            const struct setting *setting,
00326                            const void *data, size_t len );
00327 extern int fetch_setting ( struct settings *settings,
00328                            const struct setting *setting,
00329                            struct settings **origin, struct setting *fetched,
00330                            void *data, size_t len );
00331 extern int fetch_setting_copy ( struct settings *settings,
00332                                 const struct setting *setting,
00333                                 struct settings **origin,
00334                                 struct setting *fetched, void **data );
00335 extern int fetch_raw_setting ( struct settings *settings,
00336                                const struct setting *setting,
00337                                void *data, size_t len );
00338 extern int fetch_raw_setting_copy ( struct settings *settings,
00339                                     const struct setting *setting,
00340                                     void **data );
00341 extern int fetch_string_setting ( struct settings *settings,
00342                                   const struct setting *setting,
00343                                   char *data, size_t len );
00344 extern int fetch_string_setting_copy ( struct settings *settings,
00345                                        const struct setting *setting,
00346                                        char **data );
00347 extern int fetch_ipv4_array_setting ( struct settings *settings,
00348                                       const struct setting *setting,
00349                                       struct in_addr *inp, unsigned int count );
00350 extern int fetch_ipv4_setting ( struct settings *settings,
00351                                 const struct setting *setting,
00352                                 struct in_addr *inp );
00353 extern int fetch_ipv6_array_setting ( struct settings *settings,
00354                                       const struct setting *setting,
00355                                       struct in6_addr *inp, unsigned int count);
00356 extern int fetch_ipv6_setting ( struct settings *settings,
00357                                 const struct setting *setting,
00358                                 struct in6_addr *inp );
00359 extern int fetch_int_setting ( struct settings *settings,
00360                                const struct setting *setting, long *value );
00361 extern int fetch_uint_setting ( struct settings *settings,
00362                                 const struct setting *setting,
00363                                 unsigned long *value );
00364 extern long fetch_intz_setting ( struct settings *settings,
00365                                  const struct setting *setting );
00366 extern unsigned long fetch_uintz_setting ( struct settings *settings,
00367                                            const struct setting *setting );
00368 extern int fetch_uuid_setting ( struct settings *settings,
00369                                 const struct setting *setting,
00370                                 union uuid *uuid );
00371 extern void clear_settings ( struct settings *settings );
00372 extern int setting_cmp ( const struct setting *a, const struct setting *b );
00373 
00374 extern struct settings * find_child_settings ( struct settings *parent,
00375                                                const char *name );
00376 extern struct settings * autovivify_child_settings ( struct settings *parent,
00377                                                      const char *name );
00378 extern const char * settings_name ( struct settings *settings );
00379 extern struct settings * find_settings ( const char *name );
00380 extern struct setting * find_setting ( const char *name );
00381 extern int parse_setting_name ( char *name, get_child_settings_t get_child,
00382                                 struct settings **settings,
00383                                 struct setting *setting );
00384 extern int setting_name ( struct settings *settings,
00385                           const struct setting *setting,
00386                           char *buf, size_t len );
00387 extern int setting_format ( const struct setting_type *type, const void *raw,
00388                             size_t raw_len, char *buf, size_t len );
00389 extern int setting_parse ( const struct setting_type *type, const char *value,
00390                            void *buf, size_t len );
00391 extern int setting_numerate ( const struct setting_type *type, const void *raw,
00392                               size_t raw_len, unsigned long *value );
00393 extern int setting_denumerate ( const struct setting_type *type,
00394                                 unsigned long value, void *buf, size_t len );
00395 extern int fetchf_setting ( struct settings *settings,
00396                             const struct setting *setting,
00397                             struct settings **origin, struct setting *fetched,
00398                             char *buf, size_t len );
00399 extern int fetchf_setting_copy ( struct settings *settings,
00400                                  const struct setting *setting,
00401                                  struct settings **origin,
00402                                  struct setting *fetched, char **value );
00403 extern int storef_setting ( struct settings *settings,
00404                             const struct setting *setting, const char *value );
00405 extern int fetchn_setting ( struct settings *settings,
00406                             const struct setting *setting,
00407                             struct settings **origin, struct setting *fetched,
00408                             unsigned long *value );
00409 extern int storen_setting ( struct settings *settings,
00410                             const struct setting *setting,
00411                             unsigned long value );
00412 extern char * expand_settings ( const char *string );
00413 
00414 extern const struct setting_type setting_type_string __setting_type;
00415 extern const struct setting_type setting_type_uristring __setting_type;
00416 extern const struct setting_type setting_type_ipv4 __setting_type;
00417 extern const struct setting_type setting_type_ipv6 __setting_type;
00418 extern const struct setting_type setting_type_int8 __setting_type;
00419 extern const struct setting_type setting_type_int16 __setting_type;
00420 extern const struct setting_type setting_type_int32 __setting_type;
00421 extern const struct setting_type setting_type_uint8 __setting_type;
00422 extern const struct setting_type setting_type_uint16 __setting_type;
00423 extern const struct setting_type setting_type_uint32 __setting_type;
00424 extern const struct setting_type setting_type_hex __setting_type;
00425 extern const struct setting_type setting_type_hexhyp __setting_type;
00426 extern const struct setting_type setting_type_hexraw __setting_type;
00427 extern const struct setting_type setting_type_base64 __setting_type;
00428 extern const struct setting_type setting_type_uuid __setting_type;
00429 extern const struct setting_type setting_type_busdevfn __setting_type;
00430 extern const struct setting_type setting_type_dnssl __setting_type;
00431 
00432 extern const struct setting
00433 ip_setting __setting ( SETTING_IP4, ip );
00434 extern const struct setting
00435 netmask_setting __setting ( SETTING_IP4, netmask );
00436 extern const struct setting
00437 gateway_setting __setting ( SETTING_IP4, gateway );
00438 extern const struct setting
00439 dns_setting __setting ( SETTING_IP4_EXTRA, dns );
00440 extern const struct setting
00441 ip6_setting __setting ( SETTING_IP6, ip6 );
00442 extern const struct setting
00443 len6_setting __setting ( SETTING_IP6, len6 );
00444 extern const struct setting
00445 gateway6_setting __setting ( SETTING_IP6, gateway6 );
00446 extern const struct setting
00447 hostname_setting __setting ( SETTING_HOST, hostname );
00448 extern const struct setting
00449 domain_setting __setting ( SETTING_IP_EXTRA, domain );
00450 extern const struct setting
00451 filename_setting __setting ( SETTING_BOOT, filename );
00452 extern const struct setting
00453 root_path_setting __setting ( SETTING_SANBOOT, root-path );
00454 extern const struct setting
00455 san_filename_setting __setting ( SETTING_SANBOOT, san-filename );
00456 extern const struct setting
00457 username_setting __setting ( SETTING_AUTH, username );
00458 extern const struct setting
00459 password_setting __setting ( SETTING_AUTH, password );
00460 extern const struct setting
00461 priority_setting __setting ( SETTING_MISC, priority );
00462 extern const struct setting
00463 uuid_setting __setting ( SETTING_HOST, uuid );
00464 extern const struct setting
00465 next_server_setting __setting ( SETTING_BOOT, next-server );
00466 extern const struct setting
00467 mac_setting __setting ( SETTING_NETDEV, mac );
00468 extern const struct setting
00469 busid_setting __setting ( SETTING_NETDEV, busid );
00470 extern const struct setting
00471 user_class_setting __setting ( SETTING_HOST_EXTRA, user-class );
00472 extern const struct setting
00473 vendor_class_setting __setting ( SETTING_HOST_EXTRA, vendor-class );
00474 extern const struct setting
00475 manufacturer_setting __setting ( SETTING_HOST_EXTRA, manufacturer );
00476 extern const struct setting
00477 product_setting __setting ( SETTING_HOST_EXTRA, product );
00478 extern const struct setting
00479 serial_setting __setting ( SETTING_HOST_EXTRA, serial );
00480 extern const struct setting
00481 asset_setting __setting ( SETTING_HOST_EXTRA, asset );
00482 extern const struct setting
00483 board_serial_setting __setting ( SETTING_HOST_EXTRA, board-serial );
00484 extern const struct setting dhcp_server_setting __setting ( SETTING_MISC,
00485                                                             dhcp-server );
00486 
00487 /**
00488  * Initialise a settings block
00489  *
00490  * @v settings          Settings block
00491  * @v op                Settings block operations
00492  * @v refcnt            Containing object reference counter, or NULL
00493  * @v default_scope     Default scope
00494  */
00495 static inline void settings_init ( struct settings *settings,
00496                                    struct settings_operations *op,
00497                                    struct refcnt *refcnt,
00498                                    const struct settings_scope *default_scope ){
00499         INIT_LIST_HEAD ( &settings->siblings );
00500         INIT_LIST_HEAD ( &settings->children );
00501         settings->op = op;
00502         settings->refcnt = refcnt;
00503         settings->default_scope = default_scope;
00504 }
00505 
00506 /**
00507  * Initialise a settings block
00508  *
00509  * @v generics          Generic settings block
00510  * @v refcnt            Containing object reference counter, or NULL
00511  */
00512 static inline void generic_settings_init ( struct generic_settings *generics,
00513                                            struct refcnt *refcnt ) {
00514         settings_init ( &generics->settings, &generic_settings_operations,
00515                         refcnt, NULL );
00516         INIT_LIST_HEAD ( &generics->list );
00517 }
00518 
00519 /**
00520  * Delete setting
00521  *
00522  * @v settings          Settings block
00523  * @v setting           Setting to delete
00524  * @ret rc              Return status code
00525  */
00526 static inline int delete_setting ( struct settings *settings,
00527                                    const struct setting *setting ) {
00528         return store_setting ( settings, setting, NULL, 0 );
00529 }
00530 
00531 /**
00532  * Check existence of predefined setting
00533  *
00534  * @v settings          Settings block, or NULL to search all blocks
00535  * @v setting           Setting to fetch
00536  * @ret exists          Setting exists
00537  */
00538 static inline int setting_exists ( struct settings *settings,
00539                                    const struct setting *setting ) {
00540         return ( fetch_setting ( settings, setting, NULL, NULL,
00541                                  NULL, 0 ) >= 0 );
00542 }
00543 
00544 #endif /* _IPXE_SETTINGS_H */