dts: Introduce DT_STRING_TOKEN and DT_STRING_UPPER_TOKEN

To be able to get a tokenize DT string without the quotes. Deprecate
also DT_ENUM_TOKEN and DT_ENUM_UPPER_TOKEN.

Signed-off-by: Carlo Caione <[email protected]>

Author: carlocaione

doc/releases/release-notes-2.7.rst

@@ -27,6 +27,12 @@ interface and listing all issues with the `bug label
 API Changes
 ***********
 
+Deprecated in this release
+
+* :c:macro:`DT_ENUM_TOKEN` and :c:macro:`DT_ENUM_UPPER_TOKEN`,
+  were deprecated in favor of utilizing
+  :c:macro:`DT_STRING_TOKEN` and :c:macro:`DT_STRING_UPPER_TOKEN`
+
 Changes in this release
 
 ==========================

drivers/flash/nrf_qspi_nor.c

@@ -46,7 +46,7 @@ BUILD_ASSERT(INST_0_SCK_FREQUENCY >= (NRF_QSPI_BASE_CLOCK_FREQ / 16),
 #define QSPI_PROP_LEN(prop) DT_PROP_LEN(QSPI_NODE, prop)
 
 #define INST_0_QER _CONCAT(JESD216_DW15_QER_, \
-			   DT_ENUM_TOKEN(DT_DRV_INST(0), \
+			   DT_STRING_TOKEN(DT_DRV_INST(0), \
 					 quad_enable_requirements))
 
 BUILD_ASSERT(((INST_0_QER == JESD216_DW15_QER_NONE)

include/devicetree.h

@@ -41,8 +41,9 @@
  *
  * _ENUM_IDX: property's value as an index into bindings enum
  * _ENUM_TOKEN: property's value as a token into bindings enum (string
- *              enum values are identifiers)
- * _ENUM_UPPER_TOKEN: like _ENUM_TOKEN, but uppercased
+ *              enum values are identifiers) [deprecated, use _STRING_TOKEN]
+ * _ENUM_UPPER_TOKEN: like _ENUM_TOKEN, but uppercased [deprecated, use
+ *		      _STRING_UPPER_TOKEN]
  * _EXISTS: property is defined
  * _FOREACH_PROP_ELEM: helper for "iterating" over values in the property
  * _FOREACH_PROP_ELEM_VARGS: foreach functions with variable number of arguments
@@ -55,6 +56,8 @@
  * _NAME_<name>_PH: phandle array's phandle by name
  * _NAME_<name>_VAL_<val>: phandle array's property specifier by name
  * _NAME_<name>_VAL_<val>_EXISTS: cell value exists, by name
+ * _STRING_TOKEN: string property's value as a token
+ * _STRING_UPPER_TOKEN: like _STRING_TOKEN, but uppercased
  */
 
 /**
@@ -702,6 +705,113 @@
 	COND_CODE_1(DT_NODE_HAS_PROP(node_id, prop), \
 		    (DT_ENUM_IDX(node_id, prop)), (default_idx_value))
 
+/**
+ * @brief Get a string property's value as a token.
+ *
+ * This removes "the quotes" from string-valued properties, and converts
+ * non-alphanumeric characters to underscores. That can be useful, for example,
+ * when programmatically using the value to form a C variable or code.
+ *
+ * DT_STRING_TOKEN() can only be used for properties with string type.
+ *
+ * It is an error to use DT_STRING_TOKEN() in other circumstances.
+ *
+ * Example devicetree fragment:
+ *
+ *     n1: node-1 {
+ *             prop = "foo";
+ *     };
+ *     n2: node-2 {
+ *             prop = "FOO";
+ *     }
+ *     n3: node-3 {
+ *             prop = "123 foo";
+ *     };
+ *
+ * Example bindings fragment:
+ *
+ *     properties:
+ *       prop:
+ *         type: string
+ *
+ * Example usage:
+ *
+ *     DT_STRING_TOKEN(DT_NODELABEL(n1), prop) // foo
+ *     DT_STRING_TOKEN(DT_NODELABEL(n2), prop) // FOO
+ *     DT_STRING_TOKEN(DT_NODELABEL(n3), prop) // 123_foo
+ *
+ * Notice how:
+ *
+ * - Unlike C identifiers, the property values may begin with a
+ *   number. It's the user's responsibility not to use such values as
+ *   the name of a C identifier.
+ *
+ * - The uppercased "FOO" in the DTS remains @p FOO as a token. It is
+ *   *not* converted to @p foo.
+ *
+ * - The whitespace in the DTS "123 foo" string is converted to @p
+ *   123_foo as a token.
+ *
+ * @param node_id node identifier
+ * @param prop lowercase-and-underscores property string name
+ * @return the value of @p prop as a token, i.e. without any quotes
+ *         and with special characters converted to underscores
+ */
+#define DT_STRING_TOKEN(node_id, prop) \
+	DT_CAT4(node_id, _P_, prop, _STRING_TOKEN)
+
+/**
+ * @brief Like DT_STRING_TOKEN(), but uppercased.
+ *
+ * This removes "the quotes and capitalize" from string-valued properties, and
+ * converts non-alphanumeric characters to underscores. That can be useful, for
+ * example, when programmatically using the value to form a C variable or code.
+ *
+ * DT_STRING_UPPER_TOKEN() can only be used for properties with string type.
+ *
+ * It is an error to use DT_STRING_UPPER_TOKEN() in other circumstances.
+ *
+ * Example devicetree fragment:
+ *
+ *     n1: node-1 {
+ *             prop = "foo";
+ *     };
+ *     n2: node-2 {
+ *             prop = "123 foo";
+ *     };
+ *
+ * Example bindings fragment:
+ *
+ *     properties:
+ *       prop:
+ *         type: string
+ *
+ * Example usage:
+ *
+ *     DT_STRING_UPPER_TOKEN(DT_NODELABEL(n1), prop) // FOO
+ *     DT_STRING_UPPER_TOKEN(DT_NODELABEL(n2), prop) // 123_FOO
+ *
+ * Notice how:
+ *
+ * - Unlike C identifiers, the property values may begin with a
+ *   number. It's the user's responsibility not to use such values as
+ *   the name of a C identifier.
+ *
+ * - The lowercased "foo" in the DTS becomes @p FOO as a token, i.e.
+ *   it is uppercased.
+ *
+ * - The whitespace in the DTS "123 foo" string is converted to @p
+ *   123_FOO as a token, i.e. it is uppercased and whitespace becomes
+ *   an underscore.
+ *
+ * @param node_id node identifier
+ * @param prop lowercase-and-underscores property string name
+ * @return the value of @p prop as a token, i.e. without any quotes
+ *         and with special characters converted to underscores
+ */
+#define DT_STRING_UPPER_TOKEN(node_id, prop) \
+	DT_CAT4(node_id, _P_, prop, _STRING_UPPER_TOKEN)
+
 /**
  * @brief Get an enumeration property's value as a token.
  *
@@ -764,6 +874,7 @@
  *         and with special characters converted to underscores
  */
 #define DT_ENUM_TOKEN(node_id, prop) \
+	__DEPRECATED_MACRO \
 	DT_CAT4(node_id, _P_, prop, _ENUM_TOKEN)
 
 /**
@@ -823,6 +934,7 @@
  *         underscores
  */
 #define DT_ENUM_UPPER_TOKEN(node_id, prop) \
+	__DEPRECATED_MACRO \
 	DT_CAT4(node_id, _P_, prop, _ENUM_UPPER_TOKEN)
 
 /*

scripts/dts/gen_defines.py

@@ -524,6 +524,10 @@ def write_vanilla_props(node):
             # DT_N_<node-id>_P_<prop-id>
             macro2val[macro] = val
 
+        if prop.spec.type == 'string':
+            macro2val[macro + "_STRING_TOKEN"] = prop.val_as_token
+            macro2val[macro + "_STRING_UPPER_TOKEN"] = prop.val_as_token.upper()
+
         if prop.enum_index is not None:
             # DT_N_<node-id>_P_<prop-id>_ENUM_IDX
             macro2val[macro + "_ENUM_IDX"] = prop.enum_index

soc/arm/nuvoton_npcx/common/soc_dt.h

@@ -23,7 +23,7 @@
  */
 #define NPCX_DT_PROP_ENUM_OR(node_id, prop, default_value) \
 	COND_CODE_1(DT_NODE_HAS_PROP(node_id, prop), \
-		    (DT_ENUM_UPPER_TOKEN(node_id, prop)), (default_value))
+		    (DT_STRING_UPPER_TOKEN(node_id, prop)), (default_value))
 
 /**
  * @brief Like DT_INST_PROP_OR(), but expand parameters with

tests/lib/devicetree/api/src/main.c

@@ -28,6 +28,8 @@
  * - DT_INST_IO_CHANNELS_LABEL
  * - DT_INST_DMAS_LABEL_BY_IDX
  * - DT_INST_DMAS_LABEL_BY_NAME
+ * - DT_ENUM_TOKEN
+ * - DT_ENUM_UPPER_TOKEN
  */
 #define __DEPRECATED_MACRO