[settings] Explicitly separate the concept of a completed fetched setting

The fetch_setting() family of functions may currently modify the
definition of the specified setting (e.g. to add missing type
information).  Clean up this interface by requiring callers to provide
an explicit buffer to contain the completed definition of the fetched
setting, if required.

Signed-off-by: Michael Brown <mcb30@ipxe.org>

1 files changed, 99 insertions, 81 deletions

diff --git a/src/include/ipxe/settings.h b/src/include/ipxe/settings.h
index a6dfd210..25665ca7 100644
--- a/src/include/ipxe/settings.h
+++ b/src/include/ipxe/settings.h
@@ -32,7 +32,7 @@ struct setting {
 	 * This identifies the type of setting (e.g. string, IPv4
 	 * address, etc.).
 	 */
-	struct setting_type *type;
+	const struct setting_type *type;
 	/** Setting tag, if applicable
 	 *
 	 * The setting tag is a numerical description of the setting
@@ -45,7 +45,7 @@ struct setting {
 	 * For historic reasons, a NULL scope with a non-zero tag
 	 * indicates a DHCPv4 option setting.
 	 */
-	struct settings_scope *scope;
+	const struct settings_scope *scope;
 };
 
 /** Configuration setting table */
@@ -90,7 +90,7 @@ struct settings_operations {
 	 * @ret applies		Setting applies within this settings block
 	 */
 	int ( * applies ) ( struct settings *settings,
-			    struct setting *setting );
+			    const struct setting *setting );
 	/** Store value of setting
 	 *
 	 * @v settings		Settings block
@@ -99,7 +99,8 @@ struct settings_operations {
 	 * @v len		Length of setting data
 	 * @ret rc		Return status code
 	 */
-	int ( * store ) ( struct settings *settings, struct setting *setting,
+	int ( * store ) ( struct settings *settings,
+			  const struct setting *setting,
 			  const void *data, size_t len );
 	/** Fetch value of setting
 	 *
@@ -136,7 +137,7 @@ struct settings {
 	/** Settings block operations */
 	struct settings_operations *op;
 	/** Default scope for numerical settings constructed for this block */
-	struct settings_scope *default_scope;
+	const struct settings_scope *default_scope;
 };
 
 /**
@@ -193,7 +194,7 @@ struct setting_type {
 	 * @v len		Length of buffer
 	 * @ret len		Length of raw value, or negative error
 	 */
-	int ( * parse ) ( struct setting_type *type, const char *value,
+	int ( * parse ) ( const struct setting_type *type, const char *value,
 			  void *buf, size_t len );
 	/** Format setting value as a string
 	 *
@@ -204,7 +205,7 @@ struct setting_type {
 	 * @v len		Length of buffer
 	 * @ret len		Length of formatted value, or negative error
 	 */
-	int ( * format ) ( struct setting_type *type, const void *raw,
+	int ( * format ) ( const struct setting_type *type, const void *raw,
 			   size_t raw_len, char *buf, size_t len );
 	/** Convert number to setting value
 	 *
@@ -214,7 +215,8 @@ struct setting_type {
 	 * @v len		Length of buffer
 	 * @ret len		Length of raw value, or negative error
 	 */
-	int ( * denumerate ) ( struct setting_type *type, unsigned long value,
+	int ( * denumerate ) ( const struct setting_type *type,
+			       unsigned long value,
 			       void *buf, size_t len );
 	/** Convert setting value to number
 	 *
@@ -224,7 +226,7 @@ struct setting_type {
 	 * @v value		Numeric value to fill in
 	 * @ret rc		Return status code
 	 */
-	int ( * numerate ) ( struct setting_type *type, const void *raw,
+	int ( * numerate ) ( const struct setting_type *type, const void *raw,
 			     size_t raw_len, unsigned long *value );
 };
 
@@ -256,7 +258,7 @@ struct settings_applicator {
 /** A built-in setting */
 struct builtin_setting {
 	/** Setting */
-	struct setting *setting;
+	const struct setting *setting;
 	/** Fetch setting value
 	 *
 	 * @v data		Buffer to fill with setting data
@@ -273,7 +275,7 @@ struct builtin_setting {
 #define __builtin_setting __table_entry ( BUILTIN_SETTINGS, 01 )
 
 /** Built-in setting scope */
-extern struct settings_scope builtin_scope;
+extern const struct settings_scope builtin_scope;
 
 /**
  * A generic settings block
@@ -291,7 +293,7 @@ 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 struct setting *setting,
 				    const void *data, size_t len );
 extern int generic_settings_fetch ( struct settings *settings,
 				    struct setting *setting,
@@ -304,42 +306,50 @@ 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 struct setting *setting );
+extern int store_setting ( struct settings *settings,
+			   const struct setting *setting,
 			   const void *data, size_t len );
-extern int fetch_setting ( struct settings *settings, struct setting *setting,
+extern int fetch_setting ( struct settings *settings,
+			   const struct setting *setting,
+			   struct settings **origin, struct setting *fetched,
 			   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 );
+				const struct setting *setting,
+				struct settings **origin,
+				struct setting *fetched, void **data );
+extern int fetch_raw_setting ( struct settings *settings,
+			       const struct setting *setting,
+			       void *data, size_t len );
+extern int fetch_raw_setting_copy ( struct settings *settings,
+				    const struct setting *setting,
+				    void **data );
 extern int fetch_string_setting ( struct settings *settings,
-				  struct setting *setting,
+				  const struct setting *setting,
 				  char *data, size_t len );
 extern int fetch_string_setting_copy ( struct settings *settings,
-				       struct setting *setting,
+				       const struct setting *setting,
 				       char **data );
 extern int fetch_ipv4_array_setting ( struct settings *settings,
-				      struct setting *setting,
-				      struct in_addr *inp,
-				      unsigned int count );
+				      const 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 );
+				const struct setting *setting,
+				struct in_addr *inp );
 extern int fetch_int_setting ( struct settings *settings,
-			       struct setting *setting, long *value );
+			       const struct setting *setting, long *value );
 extern int fetch_uint_setting ( struct settings *settings,
-				struct setting *setting,
+				const struct setting *setting,
 				unsigned long *value );
 extern long fetch_intz_setting ( struct settings *settings,
-				 struct setting *setting );
+				 const struct setting *setting );
 extern unsigned long fetch_uintz_setting ( struct settings *settings,
-					   struct setting *setting );
+					   const struct setting *setting );
 extern int fetch_uuid_setting ( struct settings *settings,
-				struct setting *setting, union uuid *uuid );
+				const struct setting *setting,
+				union uuid *uuid );
 extern void clear_settings ( struct settings *settings );
-extern int setting_cmp ( struct setting *a, struct setting *b );
+extern int setting_cmp ( const struct setting *a, const struct setting *b );
 
 extern struct settings * find_child_settings ( struct settings *parent,
 					       const char *name );
@@ -351,61 +361,68 @@ 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,
+extern int setting_name ( struct settings *settings,
+			  const struct setting *setting,
 			  char *buf, size_t len );
-extern int setting_format ( struct setting_type *type, const void *raw,
+extern int setting_format ( const struct setting_type *type, const void *raw,
 			    size_t raw_len, char *buf, size_t len );
-extern int setting_parse ( struct setting_type *type, const char *value,
+extern int setting_parse ( const struct setting_type *type, const char *value,
 			   void *buf, size_t len );
-extern int setting_numerate ( struct setting_type *type, const void *raw,
+extern int setting_numerate ( const struct setting_type *type, const void *raw,
 			      size_t raw_len, unsigned long *value );
-extern int setting_denumerate ( struct setting_type *type, unsigned long value,
-				void *buf, size_t len );
-extern int fetchf_setting ( struct settings *settings, struct setting *setting,
+extern int setting_denumerate ( const struct setting_type *type,
+				unsigned long value, void *buf, size_t len );
+extern int fetchf_setting ( struct settings *settings,
+			    const struct setting *setting,
+			    struct settings **origin, struct setting *fetched,
 			    char *buf, size_t len );
 extern int fetchf_setting_copy ( struct settings *settings,
-				 struct setting *setting, char **value );
+				 const struct setting *setting,
+				 struct settings **origin,
+				 struct setting *fetched, char **value );
 extern int storef_setting ( struct settings *settings,
-			    struct setting *setting,
-			    const char *value );
-extern int fetchn_setting ( struct settings *settings, struct setting *setting,
+			    const struct setting *setting, const char *value );
+extern int fetchn_setting ( struct settings *settings,
+			    const struct setting *setting,
+			    struct settings **origin, struct setting *fetched,
 			    unsigned long *value );
-extern int storen_setting ( struct settings *settings, struct setting *setting,
+extern int storen_setting ( struct settings *settings,
+			    const struct setting *setting,
 			    unsigned long 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_ipv6 __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 );
-extern struct setting user_class_setting __setting ( SETTING_HOST_EXTRA );
+extern const struct setting_type setting_type_string __setting_type;
+extern const struct setting_type setting_type_uristring __setting_type;
+extern const struct setting_type setting_type_ipv4 __setting_type;
+extern const struct setting_type setting_type_ipv6 __setting_type;
+extern const struct setting_type setting_type_int8 __setting_type;
+extern const struct setting_type setting_type_int16 __setting_type;
+extern const struct setting_type setting_type_int32 __setting_type;
+extern const struct setting_type setting_type_uint8 __setting_type;
+extern const struct setting_type setting_type_uint16 __setting_type;
+extern const struct setting_type setting_type_uint32 __setting_type;
+extern const struct setting_type setting_type_hex __setting_type;
+extern const struct setting_type setting_type_hexhyp __setting_type;
+extern const struct setting_type setting_type_hexraw __setting_type;
+extern const struct setting_type setting_type_uuid __setting_type;
+extern const struct setting_type setting_type_busdevfn __setting_type;
+
+extern const struct setting ip_setting __setting ( SETTING_IPv4 );
+extern const struct setting netmask_setting __setting ( SETTING_IPv4 );
+extern const struct setting gateway_setting __setting ( SETTING_IPv4 );
+extern const struct setting dns_setting __setting ( SETTING_IPv4_EXTRA );
+extern const struct setting hostname_setting __setting ( SETTING_HOST );
+extern const struct setting domain_setting __setting ( SETTING_IPv4_EXTRA );
+extern const struct setting filename_setting __setting ( SETTING_BOOT );
+extern const struct setting root_path_setting __setting ( SETTING_SANBOOT );
+extern const struct setting username_setting __setting ( SETTING_AUTH );
+extern const struct setting password_setting __setting ( SETTING_AUTH );
+extern const struct setting priority_setting __setting ( SETTING_MISC );
+extern const struct setting uuid_setting __setting ( SETTING_HOST );
+extern const struct setting next_server_setting __setting ( SETTING_BOOT );
+extern const struct setting mac_setting __setting ( SETTING_NETDEV );
+extern const struct setting busid_setting __setting ( SETTING_NETDEV );
+extern const struct setting user_class_setting __setting ( SETTING_HOST_EXTRA );
 
 /**
  * Initialise a settings block
@@ -418,7 +435,7 @@ extern struct setting user_class_setting __setting ( SETTING_HOST_EXTRA );
 static inline void settings_init ( struct settings *settings,
 				   struct settings_operations *op,
 				   struct refcnt *refcnt,
-				   struct settings_scope *default_scope ) {
+				   const struct settings_scope *default_scope ){
 	INIT_LIST_HEAD ( &settings->siblings );
 	INIT_LIST_HEAD ( &settings->children );
 	settings->op = op;
@@ -447,20 +464,21 @@ static inline void generic_settings_init ( struct generic_settings *generics,
  * @ret rc		Return status code
  */
 static inline int delete_setting ( struct settings *settings,
-				   struct setting *setting ) {
+				   const struct setting *setting ) {
 	return store_setting ( settings, setting, NULL, 0 );
 }
 
 /**
- * Check existence of setting
+ * Check existence of predefined 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 );
+				   const struct setting *setting ) {
+	return ( fetch_setting ( settings, setting, NULL, NULL,
+				 NULL, 0 ) >= 0 );
 }
 
 #endif /* _IPXE_SETTINGS_H */