1.. _kconfig-functions:
2
3Custom Kconfig Preprocessor Functions
4#####################################
5
6Kconfiglib supports custom Kconfig preprocessor functions written in Python.
7These functions are defined in
8:zephyr_file:`scripts/kconfig/kconfigfunctions.py`.
9
10.. note::
11
12   The official Kconfig preprocessor documentation can be found `here
13   <https://www.kernel.org/doc/html/latest/kbuild/kconfig-macro-language.html>`__.
14
15See the Python docstrings in :zephyr_file:`scripts/kconfig/kconfigfunctions.py`
16for detailed documentation.
17Most of the custom preprocessor functions are used to get devicetree
18information into Kconfig. For example, the default value of a Kconfig symbol
19can be fetched from a devicetree ``reg`` property.
20
21Devicetree-related Functions
22****************************
23
24The functions listed below are used to get devicetree information into Kconfig.
25The ``*_int`` version of each function returns the value as a decimal integer,
26while the ``*_hex`` version returns a hexadecimal value starting with ``0x``.
27
28.. code-block:: none
29
30   $(dt_alias_enabled,<node alias>)
31   $(dt_chosen_bool_prop, <property in /chosen>, <prop>)
32   $(dt_chosen_enabled,<property in /chosen>)
33   $(dt_chosen_has_compat,<property in /chosen>,<compatible string>)
34   $(dt_chosen_label,<property in /chosen>)
35   $(dt_chosen_partition,addr_hex,<chosen>[,<index>,<unit>])
36   $(dt_chosen_partition,addr_int,<chosen>[,<index>,<unit>])
37   $(dt_chosen_path,<property in /chosen>)
38   $(dt_chosen_reg_addr_hex,<property in /chosen>[,<index>,<unit>])
39   $(dt_chosen_reg_addr_int,<property in /chosen>[,<index>,<unit>])
40   $(dt_chosen_reg_size_hex,<property in /chosen>[,<index>,<unit>])
41   $(dt_chosen_reg_size_int,<property in /chosen>[,<index>,<unit>])
42   $(dt_compat_any_has_prop,<compatible string>,<prop>[,<value>])
43   $(dt_compat_any_on_bus,<compatible string>,<prop>)
44   $(dt_compat_enabled,<compatible string>)
45   $(dt_compat_on_bus,<compatible string>,<bus>)
46   $(dt_gpio_hogs_enabled)
47   $(dt_has_compat,<compatible string>)
48   $(dt_node_array_prop_hex,<node path>,<prop>,<index>[,<unit>])
49   $(dt_node_array_prop_int,<node path>,<prop>,<index>[,<unit>])
50   $(dt_node_bool_prop,<node path>,<prop>)
51   $(dt_node_has_compat,<node path>,<compatible string>)
52   $(dt_node_has_prop,<node path>,<prop>)
53   $(dt_node_int_prop_hex,<node path>,<prop>[,<unit>])
54   $(dt_node_int_prop_int,<node path>,<prop>[,<unit>])
55   $(dt_node_parent,<node path>)
56   $(dt_node_ph_array_prop_hex,<node path>,<prop>,<index>,<cell>[,<unit>])
57   $(dt_node_ph_array_prop_int,<node path>,<prop>,<index>,<cell>[,<unit>])
58   $(dt_node_ph_prop_path,<node path>,<prop>)
59   $(dt_node_reg_addr_hex,<node path>[,<index>,<unit>])
60   $(dt_node_reg_addr_int,<node path>[,<index>,<unit>])
61   $(dt_node_reg_size_hex,<node path>[,<index>,<unit>])
62   $(dt_node_reg_size_int,<node path>[,<index>,<unit>])
63   $(dt_node_str_prop_equals,<node path>,<prop>,<value>)
64   $(dt_nodelabel_array_prop_has_val, <node label>, <prop>, <value>)
65   $(dt_nodelabel_bool_prop,<node label>,<prop>)
66   $(dt_nodelabel_enabled,<node label>)
67   $(dt_nodelabel_enabled_with_compat,<node label>,<compatible string>)
68   $(dt_nodelabel_has_compat,<node label>,<compatible string>)
69   $(dt_nodelabel_has_prop,<node label>,<prop>)
70   $(dt_nodelabel_path,<node label>)
71   $(dt_nodelabel_reg_addr_hex,<node label>[,<index>,<unit>])
72   $(dt_nodelabel_reg_addr_int,<node label>[,<index>,<unit>])
73   $(dt_nodelabel_reg_size_hex,<node label>[,<index>,<unit>])
74   $(dt_nodelabel_reg_size_int,<node label>[,<index>,<unit>])
75   $(dt_path_enabled,<node path>)
76
77
78Integer functions
79*****************
80
81The functions listed below can be used to do arithmetic operations
82on integer variables, such as addition, subtraction and more.
83
84.. code-block:: none
85
86   $(add,<value>[,value]...)
87   $(dec,<value>[,value]...)
88   $(div,<value>[,value]...)
89   $(inc,<value>[,value]...)
90   $(max,<value>[,value]...)
91   $(min,<value>[,value]...)
92   $(mod,<value>[,value]...)
93   $(mul,<value>[,value]...)
94   $(sub,<value>[,value]...)
95
96
97String functions
98****************
99
100The functions listed below can be used to modify string variables.
101
102.. code-block:: none
103
104   $(normalize_upper,<string>)
105   $(substring,<string>,<start>[,<stop>])
106
107
108Other functions
109***************
110
111Functions to perform specific operations, currently only a check if a shield
112name is specified.
113
114.. code-block:: none
115
116   $(shields_list_contains,<shield name>)
117
118
119Example Usage
120=============
121
122Assume that the devicetree for some board looks like this:
123
124.. code-block:: devicetree
125
126   {
127   	soc {
128   		#address-cells = <1>;
129   		#size-cells = <1>;
130
131   		spi0: spi@10014000 {
132   			compatible = "sifive,spi0";
133   			reg = <0x10014000 0x1000 0x20010000 0x3c0900>;
134   			reg-names = "control", "mem";
135   			...
136   		};
137   };
138
139The second entry in ``reg`` in ``spi@1001400`` (``<0x20010000 0x3c0900>``)
140corresponds to ``mem``, and has the address ``0x20010000``. This address can be
141inserted into Kconfig as follows:
142
143.. code-block:: kconfig
144
145   config FLASH_BASE_ADDRESS
146   	default $(dt_node_reg_addr_hex,/soc/spi@1001400,1)
147
148After preprocessor expansion, this turns into the definition below:
149
150.. code-block:: kconfig
151
152   config FLASH_BASE_ADDRESS
153   	default 0x20010000
154