devicetree: remove label property accessors

These were first deprecated in v3.2. We have kept support for them
for as long as we can, but now their presence is causing CI failures
in some configurations. Specifically, using the deprecated 'label'
property is causing a warning which is promoted to an error in some
twister runs. This is blocking other forward progress in the
devicetree API.

I tried to rework the tests to avoid this, but it was too much effort
for the time I had to work on the task. Removing the APIs is therefore
unfortunately the best way forward to unblocking other work.

Re-work the test suite a bit to maintain coverage where we are using
the label property to test other macros.

Add a migration guide section to help with the transition.

Signed-off-by: Martí Bolívar <mbolivar@amperecomputing.com>

doc/releases/migration-guide-3.6.rst

@@ -66,6 +66,52 @@ Device Drivers and Device Tree
 
   (:github:`62994`)
 
+* Various deprecated macros related to the deprecated devicetree label property
+  were removed. These are listed in the following table. The table also
+  provides replacements.
+
+  However, if you are still using code like
+  ``device_get_binding(DT_LABEL(node_id))``, consider replacing it with
+  something like ``DEVICE_DT_GET(node_id)`` instead. The ``DEVICE_DT_GET()``
+  macro avoids run-time string comparisons, and is also safer because it will
+  fail the build if the device does not exist.
+
+  .. list-table::
+     :header-rows: 1
+
+     * - Removed macro
+       - Replacement
+
+     * - ``DT_GPIO_LABEL(node_id, gpio_pha)``
+       - ``DT_PROP(DT_GPIO_CTLR(node_id, gpio_pha), label)``
+
+     * - ``DT_GPIO_LABEL_BY_IDX(node_id, gpio_pha, idx)``
+       - ``DT_PROP(DT_GPIO_CTLR_BY_IDX(node_id, gpio_pha, idx), label)``
+
+     * - ``DT_INST_GPIO_LABEL(inst, gpio_pha)``
+       - ``DT_PROP(DT_GPIO_CTLR(DT_DRV_INST(inst), gpio_pha), label)``
+
+     * - ``DT_INST_GPIO_LABEL_BY_IDX(inst, gpio_pha, idx)``
+       - ``DT_PROP(DT_GPIO_CTLR_BY_IDX(DT_DRV_INST(inst), gpio_pha, idx), label)``
+
+     * - ``DT_SPI_DEV_CS_GPIOS_LABEL(spi_dev)``
+       - ``DT_PROP(DT_SPI_DEV_CS_GPIOS_CTLR(spi_dev), label)``
+
+     * - ``DT_INST_SPI_DEV_CS_GPIOS_LABEL(inst)``
+       - ``DT_PROP(DT_SPI_DEV_CS_GPIOS_CTLR(DT_DRV_INST(inst)), label)``
+
+     * - ``DT_LABEL(node_id)``
+       - ``DT_PROP(node_id, label)``
+
+     * - ``DT_BUS_LABEL(node_id)``
+       - ``DT_PROP(DT_BUS(node_id), label)``
+
+     * - ``DT_INST_LABEL(inst)``
+       - ``DT_INST_PROP(inst, label)``
+
+     * - ``DT_INST_BUS_LABEL(inst)``
+       - ``DT_PROP(DT_BUS(DT_DRV_INST(inst)), label)``
+
 Power Management
 ================
 

dts/bindings/test/vnd,non-deprecated-label.yaml

@@ -0,0 +1,14 @@
+# Copyright 2023 Ampere Computing
+# SPDX-License-Identifier: Apache-2.0
+
+description: |
+  This can be used when we need a label property in tests without risk
+  of generating deprecation warnings, which are errors in some
+  configurations.
+
+compatible: vnd,non-deprecated-label
+
+properties:
+  label:
+    type: string
+    required: true

include/zephyr/devicetree.h

@@ -778,17 +778,6 @@
 	COND_CODE_1(DT_NODE_HAS_PROP(node_id, prop), \
 		    (DT_PROP(node_id, prop)), (default_value))
 
-/**
- * @deprecated Use DT_PROP(node_id, label)
- * @brief Equivalent to DT_PROP(node_id, label)
- *
- * This is a convenience for the Zephyr device API, which uses label
- * properties as device_get_binding() arguments.
- * @param node_id node identifier
- * @return node's label property value
- */
-#define DT_LABEL(node_id) DT_PROP(node_id, label) __DEPRECATED_MACRO
-
 /**
  * @brief Get a property value's index into its enumeration values
  *
@@ -3260,16 +3249,6 @@
  */
 #define DT_BUS(node_id) DT_CAT(node_id, _BUS)
 
-/**
- * @deprecated If used to obtain a device instance with device_get_binding,
- * consider using @c DEVICE_DT_GET(DT_BUS(node)).
- *
- * @brief Node's bus controller's `label` property
- * @param node_id node identifier
- * @return the label property of the node's bus controller DT_BUS(node)
- */
-#define DT_BUS_LABEL(node_id) DT_PROP(DT_BUS(node_id), label) __DEPRECATED_MACRO
-
 /**
  * @brief Is a node on a bus of a given type?
  *
@@ -3581,14 +3560,6 @@
 #define DT_INST_PROP_LEN_OR(inst, prop, default_value) \
 	DT_PROP_LEN_OR(DT_DRV_INST(inst), prop, default_value)
 
-/**
- * @deprecated Use DT_INST_PROP(inst, label)
- * @brief Get a `DT_DRV_COMPAT` instance's `label` property
- * @param inst instance number
- * @return instance's label property value
- */
-#define DT_INST_LABEL(inst) DT_INST_PROP(inst, label) __DEPRECATED_MACRO
-
 /**
  * @brief Get a `DT_DRV_COMPAT` instance's string property's value as a
  *        token.
@@ -3914,16 +3885,6 @@
  */
 #define DT_INST_BUS(inst) DT_BUS(DT_DRV_INST(inst))
 
-/**
- * @deprecated If used to obtain a device instance with device_get_binding,
- * consider using @c DEVICE_DT_GET(DT_INST_BUS(inst)).
- *
- * @brief Get a `DT_DRV_COMPAT`'s bus node's label property
- * @param inst instance number
- * @return the label property of the instance's bus controller
- */
-#define DT_INST_BUS_LABEL(inst) DT_BUS_LABEL(DT_DRV_INST(inst)) __DEPRECATED_MACRO
-
 /**
  * @brief Test if a `DT_DRV_COMPAT`'s bus type is a given type
  * @param inst instance number

include/zephyr/devicetree/gpio.h

@@ -65,60 +65,6 @@ extern "C" {
 #define DT_GPIO_CTLR(node_id, gpio_pha) \
 	DT_GPIO_CTLR_BY_IDX(node_id, gpio_pha, 0)
 
-/**
- * @deprecated If used to obtain a device instance with device_get_binding,
- * consider using @c DEVICE_DT_GET(DT_GPIO_CTLR_BY_IDX(node, gpio_pha, idx)).
- *
- * @brief Get a label property from a gpio phandle-array property
- *        at an index
- *
- * It's an error if the GPIO controller node referenced by the phandle
- * in node_id's "gpio_pha" property at index "idx" has no label
- * property.
- *
- * Example devicetree fragment:
- *
- *     gpio1: gpio@... {
- *             label = "GPIO_1";
- *     };
- *
- *     gpio2: gpio@... {
- *             label = "GPIO_2";
- *     };
- *
- *     n: node {
- *             gpios = <&gpio1 10 GPIO_ACTIVE_LOW>,
- *                     <&gpio2 30 GPIO_ACTIVE_HIGH>;
- *     };
- *
- * Example usage:
- *
- *     DT_GPIO_LABEL_BY_IDX(DT_NODELABEL(n), gpios, 1) // "GPIO_2"
- *
- * @param node_id node identifier
- * @param gpio_pha lowercase-and-underscores GPIO property with
- *        type "phandle-array"
- * @param idx logical index into "gpio_pha"
- * @return the label property of the node referenced at index "idx"
- * @see DT_PHANDLE_BY_IDX()
- */
-#define DT_GPIO_LABEL_BY_IDX(node_id, gpio_pha, idx) \
-	DT_PROP(DT_GPIO_CTLR_BY_IDX(node_id, gpio_pha, idx), label) __DEPRECATED_MACRO
-
-/**
- * @deprecated If used to obtain a device instance with device_get_binding,
- * consider using @c DEVICE_DT_GET(DT_GPIO_CTLR(node, gpio_pha)).
- *
- * @brief Equivalent to DT_GPIO_LABEL_BY_IDX(node_id, gpio_pha, 0)
- * @param node_id node identifier
- * @param gpio_pha lowercase-and-underscores GPIO property with
- *        type "phandle-array"
- * @return the label property of the node referenced at index 0
- * @see DT_GPIO_LABEL_BY_IDX()
- */
-#define DT_GPIO_LABEL(node_id, gpio_pha) \
-	DT_GPIO_LABEL_BY_IDX(node_id, gpio_pha, 0) __DEPRECATED_MACRO
-
 /**
  * @brief Get a GPIO specifier's pin cell at an index
  *
@@ -362,34 +308,6 @@ extern "C" {
 	COND_CODE_1(IS_ENABLED(DT_CAT4(node_id, _GPIO_HOGS_IDX_, idx, _VAL_flags_EXISTS)), \
 		    (DT_CAT4(node_id, _GPIO_HOGS_IDX_, idx, _VAL_flags)), (0))
 
-/**
- * @deprecated If used to obtain a device instance with device_get_binding,
- * consider using @c DEVICE_DT_GET(DT_INST_GPIO_CTLR_BY_IDX(node, gpio_pha, idx)).
- *
- * @brief Get a label property from a DT_DRV_COMPAT instance's GPIO
- *        property at an index
- * @param inst DT_DRV_COMPAT instance number
- * @param gpio_pha lowercase-and-underscores GPIO property with
- *        type "phandle-array"
- * @param idx logical index into "gpio_pha"
- * @return the label property of the node referenced at index "idx"
- */
-#define DT_INST_GPIO_LABEL_BY_IDX(inst, gpio_pha, idx) \
-	DT_GPIO_LABEL_BY_IDX(DT_DRV_INST(inst), gpio_pha, idx) __DEPRECATED_MACRO
-
-/**
- * @deprecated If used to obtain a device instance with device_get_binding,
- * consider using @c DEVICE_DT_GET(DT_INST_GPIO_CTLR(node, gpio_pha)).
- *
- * @brief Equivalent to DT_INST_GPIO_LABEL_BY_IDX(inst, gpio_pha, 0)
- * @param inst DT_DRV_COMPAT instance number
- * @param gpio_pha lowercase-and-underscores GPIO property with
- *        type "phandle-array"
- * @return the label property of the node referenced at index 0
- */
-#define DT_INST_GPIO_LABEL(inst, gpio_pha) \
-	DT_INST_GPIO_LABEL_BY_IDX(inst, gpio_pha, 0) __DEPRECATED_MACRO
-
 /**
  * @brief Get a DT_DRV_COMPAT instance's GPIO specifier's pin cell value
  *        at an index

include/zephyr/devicetree/spi.h

@@ -150,47 +150,6 @@ extern "C" {
 #define DT_SPI_DEV_CS_GPIOS_CTLR(spi_dev) \
 	DT_GPIO_CTLR_BY_IDX(DT_BUS(spi_dev), cs_gpios, DT_REG_ADDR(spi_dev))
 
-/**
- * @deprecated If used to obtain a device instance with device_get_binding,
- * consider using @c DEVICE_DT_GET(DT_SPI_DEV_CS_GPIOS_CTLR(node)).
- *
- * @brief Get a SPI device's chip select GPIO controller's label property
- *
- * Example devicetree fragment:
- *
- *     gpio1: gpio@... {
- *             label = "GPIO_1";
- *     };
- *
- *     gpio2: gpio@... {
- *             label = "GPIO_2";
- *     };
- *
- *     spi1: spi@... {
- *             compatible = "vnd,spi";
- *             cs-gpios = <&gpio1 10 GPIO_ACTIVE_LOW>,
- *                        <&gpio2 20 GPIO_ACTIVE_LOW>;
- *
- *             a: spi-dev-a@0 {
- *                     reg = <0>;
- *             };
- *
- *             b: spi-dev-b@1 {
- *                     reg = <1>;
- *             };
- *     };
- *
- * Example usage:
- *
- *     DT_SPI_DEV_CS_GPIOS_LABEL(DT_NODELABEL(a)) // "GPIO_1"
- *     DT_SPI_DEV_CS_GPIOS_LABEL(DT_NODELABEL(b)) // "GPIO_2"
- *
- * @param spi_dev a SPI device node identifier
- * @return label property of spi_dev's chip select GPIO controller
- */
-#define DT_SPI_DEV_CS_GPIOS_LABEL(spi_dev) \
-	DT_GPIO_LABEL_BY_IDX(DT_BUS(spi_dev), cs_gpios, DT_REG_ADDR(spi_dev)) __DEPRECATED_MACRO
-
 /**
  * @brief Get a SPI device's chip select GPIO pin number
  *
@@ -272,19 +231,6 @@ extern "C" {
 #define DT_INST_SPI_DEV_CS_GPIOS_CTLR(inst) \
 	DT_SPI_DEV_CS_GPIOS_CTLR(DT_DRV_INST(inst))
 
-/**
- * @deprecated If used to obtain a device instance with device_get_binding,
- * consider using @c DEVICE_DT_GET(DT_INST_SPI_DEV_CS_GPIOS_CTLR(node)).
- *
- * @brief Get GPIO controller name for a SPI device instance
- * This is equivalent to DT_SPI_DEV_CS_GPIOS_LABEL(DT_DRV_INST(inst)).
- * @param inst DT_DRV_COMPAT instance number
- * @return label property of the instance's chip select GPIO controller
- * @see DT_SPI_DEV_CS_GPIOS_LABEL()
- */
-#define DT_INST_SPI_DEV_CS_GPIOS_LABEL(inst) \
-	DT_SPI_DEV_CS_GPIOS_LABEL(DT_DRV_INST(inst)) __DEPRECATED_MACRO
-
 /**
  * @brief Equivalent to DT_SPI_DEV_CS_GPIOS_PIN(DT_DRV_INST(inst)).
  * @param inst DT_DRV_COMPAT instance number

tests/lib/devicetree/api/app.overlay

@@ -49,13 +49,16 @@
 		};
 
 		test_phandles: phandle-holder-0 {
+                        /*
+                         * There should only be one vnd,phandle-holder in the entire DTS.
+                         */
 			compatible = "vnd,phandle-holder";
 			/*
 			 * At least one of these phandles must refer to
 			 * test_gpio_1, or dependency ordinal tests may fail.
 			 */
 			ph = <&test_gpio_1>;
-			phs = <&test_gpio_1 &test_gpio_2 &test_i2c>;
+			phs = <&test_i2c &test_spi>;
 			phs-or = <&test_enum_default_0 &test_enum_default_1>;
 			gpios = <&test_gpio_1 10 20>, <&test_gpio_2 30 40>;
 			pha-gpios = <&test_gpio_1 50 60>, <0>, <&test_gpio_3 70>, <&test_gpio_2 80 90>;
@@ -126,7 +129,6 @@
 			reg = < 0x0 0x1000 >;
 			interrupts = <3 1>;
 			#gpio-cells = < 0x2 >;
-			label = "TEST_GPIO_0";
 			status = "disabled";
 		};
 
@@ -157,6 +159,7 @@
 			label = "TEST_GPIO_1";
 			interrupts = <4 3>;
 			status = "okay";
+                        ngpios = <100>;
 
 			test_gpio_hog_1 {
 				gpio-hog;
@@ -182,6 +185,7 @@
 			interrupts = <5 2>;
 			label = "TEST_GPIO_2";
 			status = "okay";
+                        ngpios = <200>;
 
 			test_gpio_hog_3 {
 				gpio-hog;
@@ -697,4 +701,9 @@
 			reg-names = "test_name";
 		};
 	};
+
+        non-deprecated-label {
+                compatible = "vnd,non-deprecated-label";
+                label = "FOO";
+        };
 };