From f5fd4dec3bab362a2ff7844859914e1f191fb905 Mon Sep 17 00:00:00 2001
From: Michael Brown
Date: Tue, 22 Mar 2011 16:56:35 +0000
Subject: [settings] Formalise notion of setting applicability

Expose a function setting_applies() to allow a caller to determine
whether or not a particular setting is applicable to a particular
settings block.

Restrict DHCP-backed settings blocks to accepting only DHCP-based
settings.

Restrict network device settings blocks to accepting only DHCP-based
settings and network device-specific settings such as "mac".

Inspired-by: Glenn Brown <glenn@myri.com>
Signed-off-by: Michael Brown <mcb30@ipxe.org>
---
 src/include/ipxe/settings.h | 40 ++++++++++++++++++++++++++++++++++++----
 1 file changed, 36 insertions(+), 4 deletions(-)

(limited to 'src/include/ipxe/settings.h')

diff --git a/src/include/ipxe/settings.h b/src/include/ipxe/settings.h
index d99e5ec0..b2b63f8a 100644
--- a/src/include/ipxe/settings.h
+++ b/src/include/ipxe/settings.h
@@ -33,7 +33,31 @@ struct setting {
 	 * address, etc.).
 	 */
 	struct setting_type *type;
-	/** DHCP option number, if applicable */
+	/** Setting tag, if applicable
+	 *
+	 * The setting tag is a numerical description of the setting
+	 * (such as a DHCP option number, or an SMBIOS structure and
+	 * field number).
+	 *
+	 * Users can construct tags for settings that are not
+	 * explicitly known to iPXE using the generic syntax for
+	 * numerical settings.  For example, the setting name "60"
+	 * will be interpreted as referring to DHCP option 60 (the
+	 * vendor class identifier).
+	 *
+	 * This creates a potential for namespace collisions, since
+	 * the interpretation of the numerical description will vary
+	 * according to the settings block.  When a user attempts to
+	 * fetch a generic numerical setting, we need to ensure that
+	 * only the intended settings block interprets the numerical
+	 * description.  (For example, we do not want to attempt to
+	 * retrieve the subnet mask from SMBIOS, or the system UUID
+	 * from DHCP.)
+	 *
+	 * This potential problem is resolved by allowing the setting
+	 * tag to include a "magic" value indicating the
+	 * interpretation to be placed upon the numerical description.
+	 */
 	unsigned int tag;
 };
 
@@ -45,6 +69,14 @@ struct setting {
 
 /** Settings block operations */
 struct settings_operations {
+	/** Check applicability of setting
+	 *
+	 * @v settings		Settings block
+	 * @v setting		Setting
+	 * @ret applies		Setting applies within this settings block
+	 */
+	int ( * applies ) ( struct settings *settings,
+			    struct setting *setting );
 	/** Store value of setting
 	 *
 	 * @v settings		Settings block
@@ -84,9 +116,7 @@ struct settings {
 	/** Tag magic
 	 *
 	 * This value will be ORed in to any numerical tags
-	 * constructed by parse_setting_name(), and can be used to
-	 * avoid e.g. attempting to retrieve the subnet mask from
-	 * SMBIOS, or the system UUID from DHCP.
+	 * constructed by parse_setting_name().
 	 */
 	unsigned int tag_magic;
 	/** Parent settings block */
@@ -181,6 +211,8 @@ extern int register_settings ( struct settings *settings,
 			       struct settings *parent, const char *name );
 extern void unregister_settings ( struct settings *settings );
 
+extern int setting_applies ( struct settings *settings,
+			     struct setting *setting );
 extern int store_setting ( struct settings *settings, struct setting *setting,
 			   const void *data, size_t len );
 extern int fetch_setting ( struct settings *settings, struct setting *setting,
-- 
cgit v1.2.3-55-g7522