[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>

4 files changed, 90 insertions, 4 deletions

diff --git a/src/include/ipxe/dhcpopts.h b/src/include/ipxe/dhcpopts.h
index 8fb3d2d79..c5af5d749 100644
--- a/src/include/ipxe/dhcpopts.h
+++ b/src/include/ipxe/dhcpopts.h
@@ -28,6 +28,7 @@ struct dhcp_options {
 	int ( * realloc ) ( struct dhcp_options *options, size_t len );
 };
 
+extern int dhcpopt_applies ( unsigned int tag );
 extern int dhcpopt_store ( struct dhcp_options *options, unsigned int tag,
 			   const void *data, size_t len );
 extern int dhcpopt_fetch ( struct dhcp_options *options, unsigned int tag,
diff --git a/src/include/ipxe/net80211.h b/src/include/ipxe/net80211.h
index d70eb7cb8..ac844b408 100644
--- a/src/include/ipxe/net80211.h
+++ b/src/include/ipxe/net80211.h
@@ -1183,4 +1183,25 @@ static inline u16 net80211_cts_duration ( struct net80211_device *dev,
 		 net80211_duration ( dev, size, dev->rates[dev->rate] ) );
 }
 
+/** 802.11 device setting tag magic */
+#define NET80211_SETTING_TAG_MAGIC 0x8211
+
+/**
+ * Construct 802.11 setting tag
+ *
+ * @v id		Unique identifier
+ * @ret tag		Setting tag
+ */
+#define NET80211_SETTING_TAG( id ) \
+	NETDEV_SETTING_TAG ( ( NET80211_SETTING_TAG_MAGIC << 8 ) | (id) )
+
+/** SSID setting tag */
+#define NET80211_SETTING_TAG_SSID NET80211_SETTING_TAG ( 0x01 )
+
+/** Active scanning setting tag */
+#define NET80211_SETTING_TAG_ACTIVE_SCAN NET80211_SETTING_TAG ( 0x02 )
+
+/** Wireless key setting tag */
+#define NET80211_SETTING_TAG_KEY NET80211_SETTING_TAG ( 0x03 )
+
 #endif
diff --git a/src/include/ipxe/netdevice.h b/src/include/ipxe/netdevice.h
index ac7cec521..e49191f4a 100644
--- a/src/include/ipxe/netdevice.h
+++ b/src/include/ipxe/netdevice.h
@@ -390,6 +390,38 @@ struct net_driver {
 /** Declare a network driver */
 #define __net_driver __table_entry ( NET_DRIVERS, 01 )
 
+/** Network device setting tag magic
+ *
+ * All DHCP option settings are deemed to be valid as network device
+ * settings.  There are also some extra non-DHCP settings (such as
+ * "mac"), which are marked as being valid network device settings by
+ * using a magic tag value.
+ */
+#define NETDEV_SETTING_TAG_MAGIC 0xeb
+
+/**
+ * Construct network device setting tag
+ *
+ * @v id		Unique identifier
+ * @ret tag		Setting tag
+ */
+#define NETDEV_SETTING_TAG( id ) ( ( NETDEV_SETTING_TAG_MAGIC << 24 ) | (id) )
+
+/**
+ * Check if tag is a network device setting tag
+ *
+ * @v tag		Setting tag
+ * @ret is_ours		Tag is a network device setting tag
+ */
+#define IS_NETDEV_SETTING_TAG( tag ) \
+	( ( (tag) >> 24 ) == NETDEV_SETTING_TAG_MAGIC )
+
+/** MAC address setting tag */
+#define NETDEV_SETTING_TAG_MAC NETDEV_SETTING_TAG ( 0x01 )
+
+/** Bus ID setting tag */
+#define NETDEV_SETTING_TAG_BUS_ID NETDEV_SETTING_TAG ( 0x02 )
+
 extern struct list_head net_devices;
 extern struct net_device_operations null_netdev_operations;
 extern struct settings_operations netdev_settings_operations;
diff --git a/src/include/ipxe/settings.h b/src/include/ipxe/settings.h
index d99e5ec0b..b2b63f8ad 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,