devicetree.h: add accessor API for nodes and properties

This is joint work with Kumar Gala (see signed-off-by).

Add helper macros which abstract the "true names" of each of the four
types of node identifier we intend to support (e.g. DT_ALIAS(),
DT_INST()).

These can be passed to a new DT_PROP() macro which can be used to read
the value of a devicetree property given a node identifier from one of
these four other macros, and the as-a-c-token name of the property.
Add other accessor macros and tests as well.

Add some convenience APIs for writing device drivers based on instance
numbers as well. Drivers can "#define DT_DRV_COMPAT driver_compatible"
at the top of the file, then utilize these DT_INST_* macros to access
various property defines.

For example, the uart_sifive driver can do:

  #define DT_DRV_COMPAT sifive_uart0

Then use DT_INST macros like:

  .port         = DT_INST_REG_ADDR(0),
  .sys_clk_freq = DT_INST_PROP(0, clock_frequency),

For convenience working with specific hardware, also add:

  <devicetree/gpio.h>
  <devicetree/adc.h>
  <devicetree/spi.h>

Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Signed-off-by: Kumar Gala <kumar.gala@linaro.org>

dts/bindings/test/vnd,adc.yaml

@@ -0,0 +1,15 @@
+# Copyright (c) 2020, Nordic Semiconductor ASA
+# SPDX-License-Identifier: Apache-2.0
+
+description: Test ADC
+
+compatible: "vnd,adc"
+
+include: adc-controller.yaml
+
+properties:
+    "#io-channel-cells":
+      const: 1
+
+io-channel-cells:
+    - input

dts/bindings/test/vnd,array-holder.yaml

@@ -0,0 +1,17 @@
+# Copyright (c) 2020 Nordic Semiconductor ASA
+# SPDX-License-Identifier: Apache-2.0
+
+description: Test array container
+
+compatible: "vnd,array-holder"
+
+include: [base.yaml]
+
+properties:
+  a: {type: "array"}
+  b: {type: "uint8-array"}
+  c: {type: "string-array"}
+
+gpio-cells:
+  - pin
+  - flags

dts/bindings/test/vnd,clock.yaml

@@ -0,0 +1,16 @@
+# Copyright (c) 2020 Linaro Ltd.
+# SPDX-License-Identifier: Apache-2.0
+
+description: Test Clock Controller
+
+compatible: "vnd,clock"
+
+include: [clock-controller.yaml, base.yaml]
+
+properties:
+    "#clock-cells":
+      const: 2
+
+clock-cells:
+  - bus
+  - bits

dts/bindings/test/vnd,disabled-compat.yaml

@@ -0,0 +1,8 @@
+# Copyright (c) 2020 Nordic Semiconductor ASA
+# SPDX-License-Identifier: Apache-2.0
+
+description: Test disabled compatible
+
+compatible: "vnd,disabled-compat"
+
+include: base.yaml

dts/bindings/test/vnd,enum-holder.yaml

@@ -0,0 +1,17 @@
+# Copyright (c) 2020 Nordic Semiconductor ASA
+# SPDX-License-Identifier: Apache-2.0
+
+description: Test enum property container
+
+compatible: "vnd,enum-holder"
+
+include: [base.yaml]
+
+properties:
+  val:
+    type: string
+    required: true
+    enum:
+      - "zero"
+      - "one"
+      - "two"

dts/bindings/test/vnd,gpio-one-cell.yaml

@@ -0,0 +1,21 @@
+# Copyright (c) 2020 Nordic Semiconductor ASA
+# SPDX-License-Identifier: Apache-2.0
+
+description: Test GPIO node with one cell
+
+compatible: "vnd,gpio-one-cell"
+
+include: [gpio-controller.yaml, base.yaml]
+
+properties:
+    reg:
+      required: true
+
+    label:
+      required: true
+
+    "#gpio-cells":
+      const: 1
+
+gpio-cells:
+  - pin

dts/bindings/test/vnd,gpio.yaml

@@ -0,0 +1,25 @@
+# Copyright (c) 2020 Nordic Semiconductor ASA
+# SPDX-License-Identifier: Apache-2.0
+
+description: Test GPIO node
+
+compatible: "vnd,gpio"
+
+include: [gpio-controller.yaml, base.yaml]
+
+properties:
+    reg:
+      required: true
+
+    label:
+      required: true
+
+    "#gpio-cells":
+      const: 2
+
+gpio-cells:
+  - pin
+  - flags
+
+foo-cells:
+  - foocell

dts/bindings/test/vnd,i2c-device.yaml

@@ -0,0 +1,8 @@
+# Copyright (c) 2020 Nordic Semiconductor ASA
+# SPDX-License-Identifier: Apache-2.0
+
+description: Test I2C device
+
+compatible: "vnd,i2c-device"
+
+include: i2c-device.yaml

dts/bindings/test/vnd,i2c.yaml

@@ -0,0 +1,8 @@
+# Copyright (c) 2020 Nordic Semiconductor ASA
+# SPDX-License-Identifier: Apache-2.0
+
+description: Test I2C node
+
+compatible: "vnd,i2c"
+
+include: [i2c-controller.yaml, base.yaml]

dts/bindings/test/vnd,intc.yaml

@@ -0,0 +1,19 @@
+# Copyright (c) 2020 Linaro Ltd.
+# SPDX-License-Identifier: Apache-2.0
+
+description: Test Interrupt Controller
+
+compatible: "vnd,intc"
+
+include: [interrupt-controller.yaml, base.yaml]
+
+properties:
+    reg:
+      required: true
+
+    "#interrupt-cells":
+      const: 2
+
+interrupt-cells:
+  - irq
+  - priority

dts/bindings/test/vnd,interrupt-holder.yaml

@@ -0,0 +1,15 @@
+# Copyright (c) 2020 Linaro Ltd.
+# SPDX-License-Identifier: Apache-2.0
+
+description: Test Interrupt Controller
+
+compatible: "vnd,interrupt-holder"
+
+include: [base.yaml]
+
+properties:
+    interrupts:
+      required: true
+
+    interrupt-names:
+      required: true

dts/bindings/test/vnd,phandle-holder.yaml

@@ -0,0 +1,16 @@
+# Copyright (c) 2020 Nordic Semiconductor ASA
+# SPDX-License-Identifier: Apache-2.0
+
+description: Test phandle property container
+
+compatible: "vnd,phandle-holder"
+
+include: [base.yaml]
+
+properties:
+  ph: {type: "phandle"}
+  phs: {type: "phandles"}
+  pha-gpios: {type: "phandle-array"}
+  gpios: {type: "phandle-array"}
+  foos: {type: "phandle-array"}
+  foo-names: {type: "string-array"}

dts/bindings/test/vnd,reg-holder.yaml

@@ -0,0 +1,18 @@
+# Copyright (c) 2020 Linaro Ltd.
+# SPDX-License-Identifier: Apache-2.0
+
+description: Test register property container
+
+compatible: "vnd,reg-holder"
+
+include: [base.yaml]
+
+properties:
+    reg:
+      required: true
+
+    reg-names:
+      required: true
+
+    misc-prop:
+      type: int

dts/bindings/test/vnd,spi-device-2.yaml

@@ -0,0 +1,8 @@
+# Copyright (c) 2020 Nordic Semiconductor ASA
+# SPDX-License-Identifier: Apache-2.0
+
+description: Test SPI device 2
+
+compatible: "vnd,spi-device-2"
+
+include: spi-device.yaml

dts/bindings/test/vnd,spi-device.yaml

@@ -0,0 +1,8 @@
+# Copyright (c) 2020 Nordic Semiconductor ASA
+# SPDX-License-Identifier: Apache-2.0
+
+description: Test SPI device
+
+compatible: "vnd,spi-device"
+
+include: spi-device.yaml

dts/bindings/test/vnd,spi.yaml

@@ -0,0 +1,8 @@
+# Copyright (c) 2020 Nordic Semiconductor ASA
+# SPDX-License-Identifier: Apache-2.0
+
+description: Test SPI node
+
+compatible: "vnd,spi"
+
+include: [spi-controller.yaml, base.yaml]

dts/bindings/test/vnd,temperature-sensor.yaml

@@ -0,0 +1,25 @@
+# Copyright (c) 2018, Nordic Semiconductor ASA
+# SPDX-License-Identifier: Apache-2.0
+
+description: Test ADC-based temperature sensor
+
+compatible: "vnd,adc-temp-sensor"
+
+include: base.yaml
+
+properties:
+    label:
+      required: true
+
+    io-channels:
+      type: phandle-array
+      required: true
+      description: ADC conversion channels
+
+    io-channel-names:
+      type: string-array
+      required: true
+      description: conversion channel names
+
+    clocks:
+      required: true

include/devicetree/adc.h

@@ -0,0 +1,198 @@
+/**
+ * @file
+ * @brief ADC Devicetree macro public API header file.
+ */
+
+/*
+ * Copyright (c) 2020, Linaro Ltd.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#ifndef ZEPHYR_INCLUDE_DEVICETREE_ADC_H_
+#define ZEPHYR_INCLUDE_DEVICETREE_ADC_H_
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @defgroup devicetree-adc Devicetree ADC API
+ * @{
+ */
+
+/**
+ * @brief Get IO channels controller "name" (label property) at an index
+ *
+ * It's an error if the IO channels controller referenced by the phandle
+ * in property "io_channels" at index "idx" has no label property.
+ *
+ * Example devicetree fragment:
+ *
+ *     adc1: adc@... {
+ *             label = "ADC_1";
+ *     };
+ *
+ *     adc2: adc@... {
+ *             label = "ADC_2";
+ *     };
+ *
+ *     n: node {
+ *             io-channels = <&adc1 10>, <&adc2 20>;
+ *     };
+ *
+ * Example usage:
+ *
+ *     DT_IO_CHANNELS_LABEL_BY_IDX(DT_NODELABEL(n), 1) // "ADC_2"
+ *
+ * @param node_id node identifier
+ * @param idx logical index into the property
+ * @return the label property for the referenced node at index idx
+ * @see DT_PHANDLE_BY_IDX()
+ */
+#define DT_IO_CHANNELS_LABEL_BY_IDX(node_id, idx) \
+	DT_PROP_BY_PHANDLE_IDX(node_id, io_channels, idx, label)
+
+/**
+ * @brief Get IO channels controller "name" (label property) by name
+ *
+ * It's an error if the IO channels controller referenced by the phandle
+ * in property "io_channels" at index "idx" has no label property.
+ *
+ * Example devicetree fragment:
+ *
+ *     adc1: adc@... {
+ *             label = "ADC_1";
+ *     };
+ *
+ *     adc2: adc@... {
+ *             label = "ADC_2";
+ *     };
+ *
+ *     n: node {
+ *             io-channels = <&adc1 10>, <&adc2 20>;
+ *             io-channel-names = "SENSOR", "BANDGAP";
+ *     };
+ *
+ * Example usage:
+ *
+ *     DT_IO_CHANNELS_LABEL_BY_NAME(DT_NODELABEL(n), bandgap) // "ADC_2"
+ *
+ * @param node_id node identifier
+ * @param name lowercase-and-underscores "io_channel" name
+ * @return the label property for the referenced node by name
+ * @see DT_PHANDLE_BY_NAME()
+ */
+#define DT_IO_CHANNELS_LABEL_BY_NAME(node_id, name) \
+	DT_PROP(DT_PHANDLE_BY_NAME(node_id, io_channels, name), label)
+
+/**
+ * @brief Equivalent to DT_IO_CHANNELS_LABEL_BY_IDX(node_id, 0)
+ * @param node_id node identifier
+ * @return the label property for the named specifier at index 0
+ * @see DT_IO_CHANNELS_LABEL_BY_IDX()
+ */
+#define DT_IO_CHANNELS_LABEL(node_id) DT_IO_CHANNELS_LABEL_BY_IDX(node_id, 0)
+
+/**
+ * @brief Get IO channel's controller "name" at an index
+ * (see @ref DT_IO_CHANNELS_LABEL_BY_IDX)
+ * @param inst instance number
+ * @param idx logical index into the property
+ * @return the label property for the named specifier at index idx
+ */
+#define DT_INST_IO_CHANNELS_LABEL_BY_IDX(inst, idx) \
+	DT_IO_CHANNELS_LABEL_BY_IDX(DT_DRV_INST(inst), idx)
+
+/**
+ * @brief Get IO channel's controller "name" by name
+ * (see @ref DT_IO_CHANNELS_LABEL_BY_NAME)
+ * @param inst instance number
+ * @param name lowercase-and-underscores "io_channel" name
+ * @return the label property for the named specifier by name
+ */
+#define DT_INST_IO_CHANNELS_LABEL_BY_NAME(inst, name) \
+	DT_IO_CHANNELS_LABEL_BY_NAME(DT_DRV_INST(inst), name)
+
+/**
+ * @brief Equivalent to DT_INST_IO_CHANNELS_LABEL_BY_IDX(inst, 0)
+ * @param inst instance number
+ * @return the label property for the named specifier at index 0
+ */
+#define DT_INST_IO_CHANNELS_LABEL(inst) DT_INST_IO_CHANNELS_LABEL_BY_IDX(inst, 0)
+
+/**
+ * @brief Get IO channels controller 'input' at an index
+ *
+ * This macro only works for IO channels controllers that specify a 'input'
+ * field in the phandle-array specifier.  Refer to the specific IO channels
+ * controller binding if needed.
+ *
+ * @param node_id node identifier
+ * @param idx logical index into the property
+ * @return the input value for the named specifier at index idx
+ * @see DT_PHA_BY_IDX()
+ * @see DT_PHA()
+ */
+#define DT_IO_CHANNELS_INPUT_BY_IDX(node_id, idx) \
+	DT_PHA_BY_IDX(node_id, io_channels, idx, input)
+
+/**
+ * @brief Get IO channels controller 'input' by name
+ *
+ * This macro only works for IO channels controllers that specify a 'input'
+ * field in the phandle-array specifier.  Refer to the specific IO channels
+ * controller binding if needed.
+ *
+ * @param node_id node identifier
+ * @param name lowercase-and-underscores "io_channel" name
+ * @return the input value for the named specifier by name
+ * @see DT_PHA_BY_NAME()
+ */
+#define DT_IO_CHANNELS_INPUT_BY_NAME(node_id, name) \
+	DT_PHA_BY_NAME(node_id, io_channels, name, input)
+/**
+ * @brief Equivalent to DT_IO_CHANNELS_INPUT_BY_IDX(node_id, 0)
+ * @param node_id node identifier
+ * @return the label property for the named specifier at index 0
+ * @see DT_IO_CHANNELS_INPUT_BY_IDX()
+ */
+#define DT_IO_CHANNELS_INPUT(node_id) DT_IO_CHANNELS_INPUT_BY_IDX(node_id, 0)
+
+/**
+ * @brief Get IO channel's controller "input" at an index
+ * (see @ref DT_IO_CHANNELS_INPUT_BY_IDX)
+ * @param inst instance number
+ * @param idx logical index into the property
+ * @return the input value for the named specifier at index idx
+ */
+#define DT_INST_IO_CHANNELS_INPUT_BY_IDX(inst, idx) \
+	DT_IO_CHANNELS_INPUT_BY_IDX(DT_DRV_INST(inst), idx)
+
+/**
+ * @brief Get IO channel's controller "input" by name
+ * (see @ref DT_IO_CHANNELS_INPUT_BY_NAME)
+ * @param inst instance number
+ * @param name lowercase-and-underscores "io_channel" name
+ * @return the input value for the named specifier at index idx
+ */
+#define DT_INST_IO_CHANNELS_INPUT_BY_NAME(inst, name) \
+	DT_IO_CHANNELS_INPUT_BY_NAME(DT_DRV_INST(inst), name)
+
+/**
+ * @brief Equivalent to DT_INST_IO_CHANNELS_INPUT(inst, 0)
+ * @param inst instance number
+ * @return the input property for the named specifier at index 0
+ */
+#define DT_INST_IO_CHANNELS_INPUT(inst) DT_INST_IO_CHANNELS_INPUT_BY_IDX(inst, 0)
+
+/**
+ * @}
+ */
+
+#ifdef __cplusplus
+}
+#endif
+
+
+#endif  /* ZEPHYR_INCLUDE_DEVICETREE_ADC_H_ */

include/devicetree/clocks.h

@@ -0,0 +1,153 @@
+/**
+ * @file
+ * @brief Clocks Devicetree macro public API header file.
+ */
+
+/*
+ * Copyright (c) 2020, Linaro Ltd.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#ifndef ZEPHYR_INCLUDE_DEVICETREE_CLOCKS_H_
+#define ZEPHYR_INCLUDE_DEVICETREE_CLOCKS_H_
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @defgroup devicetree-clocks Devicetree Clocks API
+ * @{
+ */
+
+/**
+ * @brief Get clock controller "name" (label property) at an index
+ *
+ * It's an error if the clock controller referenced by the phandle
+ * in property "clocks" at index "idx" has no label property.
+ *
+ * Example devicetree fragment:
+ *
+ *     clk1: clkctrl@... {
+ *             label = "CLK_1";
+ *     };
+ *
+ *     clk2: clkctrl@... {
+ *             label = "CLK_2";
+ *     };
+ *
+ *     n: node {
+ *             clocks = <&clk1 10 20>, <&clk2 30 40>;
+ *     };
+ *
+ * Example usage:
+ *
+ *     DT_CLOCKS_LABEL_BY_IDX(DT_NODELABEL(n), 1) // "CLK_2"
+ *
+ * @param node_id node identifier
+ * @param idx logical index into the property
+ * @return the label property for the referenced node at index idx
+ * @see DT_PROP_BY_PHANDLE_IDX()
+ */
+#define DT_CLOCKS_LABEL_BY_IDX(node_id, idx) \
+	DT_PROP_BY_PHANDLE_IDX(node_id, clocks, idx, label)
+
+/**
+ * @brief Equivalent to DT_CLOCKS_LABEL_BY_IDX(node_id, 0)
+ * @param node_id node identifier
+ * @return the label property for the named specifier at index 0
+ * @see DT_CLOCKS_LABEL_BY_IDX()
+ */
+#define DT_CLOCKS_LABEL(node_id) DT_CLOCKS_LABEL_BY_IDX(node_id, 0)
+
+/**
+ * @brief Get Clock controller "cell" value at an index
+ *
+ * Example devicetree fragment:
+ *
+ *     clk1: clkctrl@... {
+ *             label = "CLK_1";
+ *             #clock-cells = < 2 >;
+ *     };
+ *
+ *     n: node {
+ *             clocks = < &clk1 10 20 >, < &clk1 30 40 >;
+ *     };
+ *
+ * Bindings fragment for the gpio0 node:
+ *
+ *     clock-cells:
+ *       - bus
+ *       - bits
+ *
+ * Example usage:
+ *
+ *     DT_CLOCKS_CELL_BY_IDX(DT_NODELABEL(n), bus, 0) // 10
+ *     DT_CLOCKS_CELL_BY_IDX(DT_NODELABEL(n), bits, 1) // 40
+ *
+ * @param node_id node identifier
+ * @param cell binding's cell name within the specifier at index "idx"
+ * @param idx logical index into the property
+ * @return the value of the cell inside the specifier at index "idx"
+ * @see DT_PHA_PHANDLE_IDX()
+ */
+#define DT_CLOCKS_CELL_BY_IDX(node_id, cell, idx) \
+	DT_PHA_BY_IDX(node_id, clocks, idx, cell)
+
+/**
+ * @brief Equivalent to DT_CLOCKS_CELL_BY_IDX(node_id, cell, 0)
+ * @param node_id node identifier
+ * @param cell binding's cell name within the specifier at index 0
+ * @return the value of the cell inside the specifier at index 0
+ * @see DT_CLOCKS_CELL_BY_IDX()
+ */
+#define DT_CLOCKS_CELL(node_id, cell) DT_CLOCKS_CELL_BY_IDX(node_id, cell, 0)
+
+/**
+ * @brief Get a DT_DRV_COMPAT clock controller "name" at an index
+ * (see @ref DT_CLOCKS_LABEL_BY_IDX)
+ * @param inst instance number
+ * @param idx logical index into the property
+ * @return the label property for the named specifier at index idx
+ */
+#define DT_INST_CLOCKS_LABEL_BY_IDX(inst, idx) \
+	DT_CLOCKS_LABEL_BY_IDX(DT_DRV_INST(inst), idx)
+
+/**
+ * @brief Get a DT_DRV_COMPAT clock controller "name"
+ * (see @ref DT_CLOCKS_LABEL_BY_IDX)
+ * @param inst instance number
+ * @return the label property for the named specifier at index 0
+ */
+#define DT_INST_CLOCKS_LABEL(inst) DT_INST_CLOCKS_LABEL_BY_IDX(inst, 0)
+
+/**
+ * @brief Get a DT_DRV_COMPAT clock controller "cell" value at an index
+ * @param inst instance number
+ * @param cell binding's cell name within the specifier at index "idx"
+ * @param idx logical index into the property
+ * @return the value of the cell inside the specifier at index "idx"
+ */
+#define DT_INST_CLOCKS_CELL_BY_IDX(inst, cell, idx) \
+	DT_CLOCKS_CELL_BY_IDX(DT_DRV_INST(inst), cell, idx)
+
+/**
+ * @brief Get a DT_DRV_COMPAT clock controller "cell" value at an index 0
+ * @param inst instance number
+ * @param cell binding's cell name within the specifier at index 0
+ * @return the value of the cell inside the specifier at index 0
+ */
+#define DT_INST_CLOCKS_CELL(inst, cell) \
+	DT_INST_CLOCKS_CELL_BY_IDX(inst, cell, 0)
+
+/**
+ * @}
+ */
+
+#ifdef __cplusplus
+}
+#endif
+
+
+#endif  /* ZEPHYR_INCLUDE_DEVICETREE_CLOCKS_H_ */

include/devicetree/gpio.h

@@ -0,0 +1,202 @@
+/**
+ * @file
+ * @brief GPIO Devicetree macro public API header file.
+ */
+
+/*
+ * Copyright (c) 2020, Linaro Ltd.
+ * Copyright (c) 2020 Nordic Semiconductor
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#ifndef ZEPHYR_INCLUDE_DEVICETREE_GPIO_H_
+#define ZEPHYR_INCLUDE_DEVICETREE_GPIO_H_
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @defgroup devicetree-gpio Devicetree GPIO API
+ * @{
+ */
+
+/**
+ * @brief Get gpio controller "name" (label property) at an index
+ *
+ * It's an error if the GPIO controller referenced by the phandle
+ * in property "gpio_pha" 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 20>, <&gpio2 30 40>;
+ *     };
+ *
+ * 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 the property
+ * @return the label property for the referenced node at index idx
+ * @see DT_PHANDLE_BY_IDX()
+ */
+#define DT_GPIO_LABEL_BY_IDX(node_id, gpio_pha, idx) \
+	DT_PROP_BY_PHANDLE_IDX(node_id, gpio_pha, idx, label)
+
+/**
+ * @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 for the named specifier 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)
+
+/**
+ * @brief Get gpio controller 'pin' at an index
+ *
+ * This macro only works for GPIO controllers that specify a 'pin'
+ * field in the phandle-array specifier.  Refer to the specific GPIO
+ * controller binding if needed.
+ *
+ * @param node_id node identifier
+ * @param gpio_pha lowercase-and-underscores GPIO property with
+ *        type "phandle-array"
+ * @param idx logical index into the property
+ * @return the pin value for the named specifier at index idx
+ * @see DT_PHA_BY_IDX()
+ * @see DT_PHA()
+ */
+#define DT_GPIO_PIN_BY_IDX(node_id, gpio_pha, idx) \
+	DT_PHA_BY_IDX(node_id, gpio_pha, idx, pin)
+
+/**
+ * @brief Equivalent to DT_GPIO_PIN_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 pin value for the named specifier at index idx
+ * @see DT_GPIO_PIN_BY_IDX()
+ */
+#define DT_GPIO_PIN(node_id, gpio_pha) \
+	DT_GPIO_PIN_BY_IDX(node_id, gpio_pha, 0)
+
+/**
+ * @brief Get gpio controller 'flags' at an index
+ *
+ * This macro only works for GPIO controllers that specify a 'flags'
+ * field in the phandle-array specifier.  Refer to the specific GPIO
+ * controller binding if needed.
+ *
+ * @param node_id node identifier
+ * @param gpio_pha lowercase-and-underscores GPIO property with
+ *        type "phandle-array"
+ * @param idx logical index into the property
+ * @return the flags value for the named specifier at index idx
+ * @see DT_PHA_BY_IDX()
+ * @see DT_PHA()
+ */
+#define DT_GPIO_FLAGS_BY_IDX(node_id, gpio_pha, idx) \
+	DT_PHA_BY_IDX(node_id, gpio_pha, idx, flags)
+
+/**
+ * @brief Equivalent to DT_GPIO_FLAGS_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 flags value for the named specifier at index idx
+ * @see DT_GPIO_FLAGS_BY_IDX()
+ */
+#define DT_GPIO_FLAGS(node_id, gpio_pha) \
+	DT_GPIO_FLAGS_BY_IDX(node_id, gpio_pha, 0)
+
+/**
+ * @brief Get gpio controller "name" at an index (see @ref DT_GPIO_LABEL_BY_IDX)
+ * @param inst instance number
+ * @param gpio_pha lowercase-and-underscores GPIO property with
+ *        type "phandle-array"
+ * @param idx logical index into the property
+ * @return the label property for the named specifier 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)
+
+/**
+ * @brief Equivalent to DT_INST_GPIO_LABEL_BY_IDX(inst, gpio_pha, 0)
+ * @param inst instance number
+ * @param gpio_pha lowercase-and-underscores GPIO property with
+ *        type "phandle-array"
+ * @return the label property for the named specifier at index 0
+ */
+#define DT_INST_GPIO_LABEL(inst, gpio_pha) \
+	DT_INST_GPIO_LABEL_BY_IDX(inst, gpio_pha, 0)
+
+/**
+ * @brief Get gpio controller "pin" at an index (see @ref DT_GPIO_PIN_BY_IDX)
+ * @param inst instance number
+ * @param gpio_pha lowercase-and-underscores GPIO property with
+ *        type "phandle-array"
+ * @param idx logical index into the property
+ * @return the pin value for the named specifier at index idx
+ */
+#define DT_INST_GPIO_PIN_BY_IDX(inst, gpio_pha, idx) \
+	DT_GPIO_PIN_BY_IDX(DT_DRV_INST(inst), gpio_pha, idx)
+
+/**
+ * @brief Equivalent to DT_INST_GPIO_PIN_BY_IDX(inst, gpio_pha, 0)
+ * @param inst instance number
+ * @param gpio_pha lowercase-and-underscores GPIO property with
+ *        type "phandle-array"
+ * @return the pin value for the named specifier at index 0
+ * @see DT_INST_GPIO_PIN_BY_IDX()
+ */
+#define DT_INST_GPIO_PIN(inst, gpio_pha) \
+	DT_INST_GPIO_PIN_BY_IDX(inst, gpio_pha, 0)
+
+/**
+ * @brief Get a devicetree property value (see @ref DT_GPIO_FLAGS_BY_IDX)
+ * @param inst instance number
+ * @param gpio_pha lowercase-and-underscores GPIO property with
+ *        type "phandle-array"
+ * @param idx logical index into the property
+ * @return a representation of the property's value
+ */
+#define DT_INST_GPIO_FLAGS_BY_IDX(inst, gpio_pha, idx) \
+	DT_GPIO_FLAGS_BY_IDX(DT_DRV_INST(inst), gpio_pha, idx)
+
+/**
+ * @brief Equivalent to DT_INST_GPIO_FLAGS_BY_IDX(inst, gpio_pha, 0)
+ * @param inst instance number
+ * @param gpio_pha lowercase-and-underscores GPIO property with
+ *        type "phandle-array"
+ * @return the flags value for the named specifier at index 0
+ * @see DT_INST_GPIO_FLAGS_BY_IDX()
+ */
+#define DT_INST_GPIO_FLAGS(inst, gpio_pha) \
+	DT_INST_GPIO_FLAGS_BY_IDX(inst, gpio_pha, 0)
+
+/**
+ * @}
+ */
+
+#ifdef __cplusplus
+}
+#endif
+
+
+#endif  /* ZEPHYR_INCLUDE_DEVICETREE_GPIO_H_ */

include/devicetree/spi.h

@@ -0,0 +1,121 @@
+/**
+ * @file
+ * @brief SPI Devicetree macro public API header file.
+ */
+
+/*
+ * Copyright (c) 2020 Nordic Semiconductor
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#ifndef ZEPHYR_INCLUDE_DEVICETREE_SPI_H_
+#define ZEPHYR_INCLUDE_DEVICETREE_SPI_H_
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @defgroup devicetree-spi Devicetree SPI API
+ * @{
+ */
+
+/**
+ * @brief Does a SPI controller have chip select GPIOs configured?
+ * The commonly used "cs-gpios" property is used for this test.
+ * @param spi node identifier for a SPI bus controller
+ * @return 1 if it has a cs-gpios property, 0 otherwise
+ */
+#define DT_SPI_HAS_CS(spi) DT_NODE_HAS_PROP(spi, cs_gpios)
+
+/**
+ * @brief The number of chip select GPIOs in a SPI controller
+ * @param spi node identifier for a SPI bus controller
+ * @return The length of its cs-gpios, or 0 if it doesn't have one
+ */
+#define DT_SPI_NUM_CS(spi) \
+	COND_CODE_1(DT_SPI_HAS_CS(spi), \
+		    (DT_PROP_LEN(spi, cs_gpios)), (0))
+
+/**
+ * @brief Does a SPI device have a chip select line in DT?
+ * @param spi_dev node identifier for a SPI device
+ * @return 1 if the SPI device's bus DT_BUS(spi_dev) has a CS
+ *         pin at index DT_REG_ADDR(spi_dev), 0 otherwise
+ */
+#define DT_SPI_DEV_HAS_CS(spi_dev) DT_SPI_HAS_CS(DT_BUS(spi_dev))
+
+/**
+ * @brief Get GPIO controller name for a SPI device's chip select
+ * DT_SPI_DEV_HAS_CS(spi_dev) must expand to 1.
+ * @brief spi_dev a SPI device node identifier
+ * @return label property of spi_dev's chip select GPIO controller
+ */
+#define DT_SPI_DEV_CS_GPIO_LABEL(spi_dev) \
+	DT_GPIO_LABEL_BY_IDX(DT_BUS(spi_dev), cs_gpios, DT_REG_ADDR(spi_dev))
+
+/**
+ * @brief Get GPIO specifier 'pin' value for a SPI device's chip select
+ * It's an error if the GPIO specifier for spi_dev's entry in its
+ * bus node's cs-gpios property has no 'pin' value.
+ * @brief spi_dev a SPI device node identifier
+ * @return pin number of spi_dev's chip select GPIO
+ */
+#define DT_SPI_DEV_CS_GPIO_PIN(spi_dev) \
+	DT_GPIO_PIN_BY_IDX(DT_BUS(spi_dev), cs_gpios, DT_REG_ADDR(spi_dev))
+
+/**
+ * @brief Get GPIO specifier 'flags' value for a SPI device's chip select
+ * It's an error if the GPIO specifier for spi_dev's entry in its
+ * bus node's cs-gpios property has no 'flags' value.
+ * @brief spi_dev a SPI device node identifier
+ * @return flags value of spi_dev's chip select GPIO specifier
+ */
+#define DT_SPI_DEV_CS_GPIO_FLAGS(spi_dev) \
+	DT_GPIO_FLAGS_BY_IDX(DT_BUS(spi_dev), cs_gpios, DT_REG_ADDR(spi_dev))
+
+/**
+ * @brief Equivalent to DT_SPI_DEV_HAS_CS(DT_DRV_INST(inst))
+ * @param inst instance number
+ * @return 1 if the instance's bus has a CS pin at index
+ *         DT_INST_REG_ADDR(inst), 0 otherwise
+ */
+#define DT_INST_SPI_DEV_HAS_CS(inst) DT_SPI_DEV_HAS_CS(DT_DRV_INST(inst))
+
+/**
+ * @brief Get GPIO controller name for a SPI device instance
+ * This is equivalent to DT_SPI_DEV_CS_GPIO_LABEL(DT_DRV_INST(inst)).
+ * @brief inst instance number
+ * @return label property of the instance's chip select GPIO controller
+ */
+#define DT_INST_SPI_DEV_CS_GPIO_LABEL(inst) \
+	DT_SPI_DEV_CS_GPIO_LABEL(DT_DRV_INST(inst))
+
+/**
+ * @brief Get GPIO specifier "pin" value for a SPI device instance
+ * This is equivalent to DT_SPI_DEV_CS_GPIO_PIN(DT_DRV_INST(inst)).
+ * @brief inst a SPI device instance number
+ * @return pin number of the instance's chip select GPIO
+ */
+#define DT_INST_SPI_DEV_CS_GPIO_PIN(inst) \
+	DT_SPI_DEV_CS_GPIO_PIN(DT_DRV_INST(inst))
+
+/**
+ * @brief Get GPIO specifier "flags" value for a SPI device instance
+ * This is equivalent to DT_SPI_DEV_CS_GPIO_FLAGS(DT_DRV_INST(inst)).
+ * @brief inst a SPI device instance number
+ * @return flags value of the instance's chip select GPIO specifier
+ */
+#define DT_INST_SPI_DEV_CS_GPIO_FLAGS(inst) \
+	DT_SPI_DEV_CS_GPIO_FLAGS(DT_DRV_INST(inst))
+
+/**
+ * @}
+ */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif  /* ZEPHYR_INCLUDE_DEVICETREE_SPI_H_ */

tests/lib/devicetree/CMakeLists.txt

@@ -0,0 +1,10 @@
+# SPDX-License-Identifier: Apache-2.0
+
+cmake_minimum_required(VERSION 3.13.1)
+
+set(DTS_ROOTS ${CMAKE_CURRENT_LIST_DIR})
+include($ENV{ZEPHYR_BASE}/cmake/app/boilerplate.cmake NO_POLICY_SCOPE)
+project(devicetree)
+
+FILE(GLOB app_sources src/*.c)
+target_sources(app PRIVATE ${app_sources})

tests/lib/devicetree/README

@@ -0,0 +1 @@
+Test cases for the devicetree.h API.

tests/lib/devicetree/app.overlay

@@ -0,0 +1,247 @@
+/*
+ * Copyright (c) 2020 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Application overlay for testing the devicetree.h API.
+ *
+ * Names in this file should be chosen in a way that won't conflict
+ * with real-world devicetree nodes, to allow these tests to run on
+ * (and be extended to test) real hardware.
+ */
+
+/ {
+	aliases {
+		test-alias = &test_nodelabel;
+	};
+
+	chosen {
+		ztest,gpio = &test_nodelabel;
+	};
+
+	test {
+		#address-cells = < 0x1 >;
+		#size-cells = < 0x1 >;
+		interrupt-parent = <&test_intc>;
+
+		test_arrays: array-holder {
+			/* vnd,undefined-compat is for DT_NODE_HAS_COMPAT() */
+			compatible = "vnd,array-holder", "vnd,undefined-compat";
+			a = <1000 2000 3000>;
+			b = [aa bb cc dd];
+			c = "bar", "baz";
+		};
+
+		test_phandles: phandle-holder-0 {
+			compatible = "vnd,phandle-holder";
+			ph = <&test_gpio_1>;
+			phs = <&test_gpio_1 &test_gpio_2 &test_i2c>;
+			gpios = <&test_gpio_1 10 20>, <&test_gpio_2 30 40>;
+			pha-gpios = <&test_gpio_1 50 60>, <&test_gpio_3 70>, <&test_gpio_2 80 90>;
+			foos = <&test_gpio_1 100>, <&test_gpio_2 110>;
+			foo-names = "A", "b-c";
+		};
+
+		test_enum_0: enum-0 {
+			compatible = "vnd,enum-holder";
+			val = "zero";
+		};
+
+		test_enum_1: enum-1 {
+			compatible = "vnd,enum-holder";
+			val = "two";
+		};
+
+		/*
+		 * This should be the only node with this
+		 * compatible in the tree.
+		 */
+		disabled-node@0 {
+			compatible = "vnd,disabled-compat";
+			reg = < 0x0 0x1000 >;
+			label = "DISABLED_NODE_0";
+			status = "disabled";
+		};
+
+		disabled_gpio: gpio@0 {
+			compatible = "vnd,gpio";
+			gpio-controller;
+			reg = < 0x0 0x1000 >;
+			interrupts = <3 1>;
+			#gpio-cells = < 0x2 >;
+			label = "TEST_GPIO_0";
+			status = "disabled";
+		};
+
+		test_nodelabel: TEST_NODELABEL_ALLCAPS: test_gpio_1: gpio@deadbeef {
+			compatible = "vnd,gpio";
+			gpio-controller;
+			reg = < 0xdeadbeef 0x1000 >;
+			#gpio-cells = < 0x2 >;
+			#foo-cells = < 0x1 >;
+			label = "TEST_GPIO_1";
+			interrupts = <4 3>;
+			status = "okay";
+		};
+
+		test_gpio_2: gpio@abcd1234 {
+			compatible = "vnd,gpio";
+			gpio-controller;
+			reg = < 0xabcd1234 0x500 0x98765432 0xff >;
+			reg-names = "one", "two";
+			#gpio-cells = < 0x2 >;
+			#foo-cells = < 0x1 >;
+			interrupts = <5 2>;
+			label = "TEST_GPIO_2";
+			status = "okay";
+		};
+
+		test_gpio_3: gpio@1234 {
+			compatible = "vnd,gpio-one-cell";
+			gpio-controller;
+			reg = < 0x1234 0x500 >;
+			#gpio-cells = < 0x1 >;
+			label = "TEST_GPIO_3";
+			status = "okay";
+		};
+
+		test_i2c: i2c@11112222 {
+			#address-cells = < 1 >;
+			#size-cells = < 0 >;
+			compatible = "vnd,i2c";
+			reg = < 0x11112222 0x1000 >;
+			label = "TEST_I2C_CTLR";
+			status = "okay";
+			clock-frequency = < 100000 >;
+			interrupts = <6 2 7 1>;
+			interrupt-names = "status", "error";
+
+			test-i2c-dev@10 {
+				compatible = "vnd,i2c-device";
+				label = "TEST_I2C_DEV_10";
+				reg = < 0x10 >;
+			};
+		};
+
+		test_spi: spi@33334444 {
+			#address-cells = < 1 >;
+			#size-cells = < 0 >;
+			compatible = "vnd,spi";
+			reg = < 0x33334444 0x1000 >;
+			interrupts = <8 3 9 0 10 1>;
+			label = "TEST_SPI_CTLR";
+			status = "okay";
+			clock-frequency = < 2000000 >;
+
+			cs-gpios = <&test_gpio_1 0x10 0x20>,
+					<&test_gpio_2 0x30 0x40>;
+
+			/* all vnd,spi-device instances should have CS */
+
+			test-spi-dev@0 {
+				compatible = "vnd,spi-device";
+				label = "TEST_SPI_DEV_0";
+				reg = <0>;
+				spi-max-frequency = < 2000000 >;
+			};
+
+			test-spi-dev@1 {
+				compatible = "vnd,spi-device";
+				label = "TEST_SPI_DEV_1";
+				reg = <1>;
+				spi-max-frequency = < 2000000 >;
+			};
+		};
+
+		test_spi_no_cs: spi@55556666 {
+			#address-cells = < 1 >;
+			#size-cells = < 0 >;
+			compatible = "vnd,spi";
+			reg = < 0x55556666 0x1000 >;
+			label = "TEST_SPI_CTLR_NO_CS";
+			status = "okay";
+			clock-frequency = < 2000000 >;
+
+			/* no vnd,spi-device-2 instances should have CS */
+			test_spi_dev_no_cs: test-spi-dev@0 {
+				compatible = "vnd,spi-device-2";
+				label = "TEST_SPI_DEV_NO_CS";
+				reg = <0>;
+				spi-max-frequency = < 2000000 >;
+			};
+		};
+
+		test_i2c_1: i2c@77778888 {
+			#address-cells = < 1 >;
+			#size-cells = < 0 >;
+			compatible = "vnd,i2c";
+			reg = < 0x77778888 0x1000 >;
+			label = "TEST_I2C_CTLR_1";
+			status = "okay";
+			clock-frequency = < 100000 >;
+			interrupts = <11 3 12 2>;
+			interrupt-names = "status", "error";
+		};
+
+		test_adc_1: adc@10002000 {
+			reg = <0x10002000 0x1000>;
+			compatible = "vnd,adc";
+			label = "TEST_ADC_1";
+			status = "okay";
+			#io-channel-cells = <1>;
+		};
+
+		test_adc_2: adc@10003000 {
+			reg = <0x10003000 0x1000>;
+			compatible = "vnd,adc";
+			label = "TEST_ADC_2";
+			status = "okay";
+			#io-channel-cells = <1>;
+		};
+
+		/* there should only be one of these */
+		test_temp_sensor: temperature-sensor {
+			compatible = "vnd,adc-temp-sensor";
+			label = "TEST_TEMP";
+			io-channels = <&test_adc_1 10>, <&test_adc_2 20>;
+			io-channel-names = "ch1", "ch2";
+			clocks = <&test_clk 3 7>, <&test_fixed_clk>, <&test_clk 8 2>;
+		};
+
+		/* there should only be one of these */
+		test_reg: reg-holder@9999aaaa {
+			compatible = "vnd,reg-holder";
+			reg = < 0x9999aaaa 0x1000 0xbbbbcccc 0x3f >;
+			status = "okay";
+			reg-names = "first", "second";
+			misc-prop = <1234>;
+		};
+
+		test_intc: interrupt-controller@bbbbcccc  {
+			compatible = "vnd,intc";
+			reg = <0xbbbbcccc 0x1000>;
+			interrupt-controller;
+			#interrupt-cells = <2>;
+		};
+
+		/* there should only be one of these */
+		test_irq: interrupt-holder {
+			compatible = "vnd,interrupt-holder";
+			status = "okay";
+			interrupts = <30 3 40 5 60 7>;
+			interrupt-names = "err", "stat", "done";
+		};
+
+		test_fixed_clk: test-fixed-clock {
+			compatible = "fixed-clock";
+			clock-frequency = <25000000>;
+			#clock-cells = <0>;
+		};
+
+		test_clk: test-clock {
+			compatible = "vnd,clock";
+                        label = "TEST_CLOCK";
+			#clock-cells = <2>;
+		};
+	};
+};

tests/lib/devicetree/prj.conf

@@ -0,0 +1 @@
+CONFIG_ZTEST=y

tests/lib/devicetree/testcase.yaml

@@ -0,0 +1,6 @@
+tests:
+  libraries.devicetree:
+    tags: devicetree
+    # We only need this to run on one platform so use native_posix as it
+    # will mostly likely be the fastest.
+    platform_whitelist: native_posix