1.. _dt-inferred-bindings:
2.. _dt-zephyr-user:
3
4The ``/zephyr,user`` node
5#########################
6
7Zephyr's devicetree scripts handle the ``/zephyr,user`` node as a special case:
8you can put essentially arbitrary properties inside it and retrieve their
9values without having to write a binding. It is meant as a convenient container
10when only a few simple properties are needed.
11
12.. note::
13
14   This node is meant for sample code and user applications. It should not be
15   used in the upstream Zephyr source code for device drivers, subsystems, etc.
16
17Simple values
18*************
19
20You can store numeric or array values in ``/zephyr,user`` if you want them to
21be configurable at build time via devicetree.
22
23For example, with this devicetree overlay:
24
25.. code-block:: devicetree
26
27   / {
28	zephyr,user {
29		boolean;
30		bytes = [81 82 83];
31		number = <23>;
32		numbers = <1>, <2>, <3>;
33		string = "text";
34		strings = "a", "b", "c";
35	};
36   };
37
38You can get the above property values in C/C++ code like this:
39
40.. code-block:: C
41
42   #define ZEPHYR_USER_NODE DT_PATH(zephyr_user)
43
44   DT_PROP(ZEPHYR_USER_NODE, boolean) // 1
45   DT_PROP(ZEPHYR_USER_NODE, bytes)   // {0x81, 0x82, 0x83}
46   DT_PROP(ZEPHYR_USER_NODE, number)  // 23
47   DT_PROP(ZEPHYR_USER_NODE, numbers) // {1, 2, 3}
48   DT_PROP(ZEPHYR_USER_NODE, string)  // "text"
49   DT_PROP(ZEPHYR_USER_NODE, strings) // {"a", "b", "c"}
50
51Devices
52*******
53
54You can store :ref:`phandles <dt-phandles>` in ``/zephyr,user`` if you want to
55be able to reconfigure which devices your application uses in simple cases
56using devicetree overlays.
57
58For example, with this devicetree overlay:
59
60.. code-block:: devicetree
61
62   / {
63	zephyr,user {
64		handle = <&gpio0>;
65		handles = <&gpio0>, <&gpio1>;
66        };
67   };
68
69You can convert the phandles in the ``handle`` and ``handles`` properties to
70device pointers like this:
71
72.. code-block:: C
73
74   /*
75    * Same thing as:
76    *
77    * ... my_dev = DEVICE_DT_GET(DT_NODELABEL(gpio0));
78    */
79   const struct device *my_device =
80   	DEVICE_DT_GET(DT_PROP(ZEPHYR_USER_NODE, handle));
81
82   #define PHANDLE_TO_DEVICE(node_id, prop, idx) \
83        DEVICE_DT_GET(DT_PHANDLE_BY_IDX(node_id, prop, idx)),
84
85   /*
86    * Same thing as:
87    *
88    * ... *my_devices[] = {
89    *         DEVICE_DT_GET(DT_NODELABEL(gpio0)),
90    *         DEVICE_DT_GET(DT_NODELABEL(gpio1)),
91    * };
92    */
93   const struct device *my_devices[] = {
94   	DT_FOREACH_PROP_ELEM(ZEPHYR_USER_NODE, handles, PHANDLE_TO_DEVICE)
95   };
96
97GPIOs
98*****
99
100The ``/zephyr,user`` node is a convenient place to store application-specific
101GPIOs that you want to be able to reconfigure with a devicetree overlay.
102
103For example, with this devicetree overlay:
104
105.. code-block:: devicetree
106
107   #include <zephyr/dt-bindings/gpio/gpio.h>
108
109   / {
110	zephyr,user {
111		signal-gpios = <&gpio0 1 GPIO_ACTIVE_HIGH>;
112        };
113   };
114
115You can convert the pin defined in ``signal-gpios`` to a ``struct
116gpio_dt_spec`` in your source code, then use it like this:
117
118.. code-block:: C
119
120   #include <zephyr/drivers/gpio.h>
121
122   #define ZEPHYR_USER_NODE DT_PATH(zephyr_user)
123
124   const struct gpio_dt_spec signal =
125           GPIO_DT_SPEC_GET(ZEPHYR_USER_NODE, signal_gpios);
126
127   /* Configure the pin */
128   gpio_pin_configure_dt(&signal, GPIO_OUTPUT_INACTIVE);
129
130   /* Set the pin to its active level */
131   gpio_pin_set_dt(&signal, 1);
132
133(See :c:struct:`gpio_dt_spec`, :c:macro:`GPIO_DT_SPEC_GET`, and
134:c:func:`gpio_pin_configure_dt` for details on these APIs.)
135