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_enabled_num,<compatible string>)
46   $(dt_compat_on_bus,<compatible string>,<bus>)
47   $(dt_gpio_hogs_enabled)
48   $(dt_has_compat,<compatible string>)
49   $(dt_node_array_prop_hex,<node path>,<prop>,<index>[,<unit>])
50   $(dt_node_array_prop_int,<node path>,<prop>,<index>[,<unit>])
51   $(dt_node_bool_prop,<node path>,<prop>)
52   $(dt_node_has_compat,<node path>,<compatible string>)
53   $(dt_node_has_prop,<node path>,<prop>)
54   $(dt_node_int_prop_hex,<node path>,<prop>[,<unit>])
55   $(dt_node_int_prop_int,<node path>,<prop>[,<unit>])
56   $(dt_node_parent,<node path>)
57   $(dt_node_ph_array_prop_hex,<node path>,<prop>,<index>,<cell>[,<unit>])
58   $(dt_node_ph_array_prop_int,<node path>,<prop>,<index>,<cell>[,<unit>])
59   $(dt_node_ph_prop_path,<node path>,<prop>)
60   $(dt_node_reg_addr_hex,<node path>[,<index>,<unit>])
61   $(dt_node_reg_addr_int,<node path>[,<index>,<unit>])
62   $(dt_node_reg_size_hex,<node path>[,<index>,<unit>])
63   $(dt_node_reg_size_int,<node path>[,<index>,<unit>])
64   $(dt_node_str_prop_equals,<node path>,<prop>,<value>)
65   $(dt_nodelabel_array_prop_has_val, <node label>, <prop>, <value>)
66   $(dt_nodelabel_bool_prop,<node label>,<prop>)
67   $(dt_nodelabel_enabled,<node label>)
68   $(dt_nodelabel_enabled_with_compat,<node label>,<compatible string>)
69   $(dt_nodelabel_exists,<node label>)
70   $(dt_nodelabel_has_compat,<node label>,<compatible string>)
71   $(dt_nodelabel_has_prop,<node label>,<prop>)
72   $(dt_nodelabel_path,<node label>)
73   $(dt_nodelabel_reg_addr_hex,<node label>[,<index>,<unit>])
74   $(dt_nodelabel_reg_addr_int,<node label>[,<index>,<unit>])
75   $(dt_nodelabel_reg_size_hex,<node label>[,<index>,<unit>])
76   $(dt_nodelabel_reg_size_int,<node label>[,<index>,<unit>])
77   $(dt_path_enabled,<node path>)
78
79
80Integer functions
81*****************
82
83The functions listed below can be used to do arithmetic operations
84on integer variables, such as addition, subtraction and more.
85Functions with and without the ``_hex`` suffix in their names
86return hexadecimal and decimal values respectively.
87
88.. code-block:: none
89
90   $(add,<value>[,value]...)
91   $(add_hex,<value>[,value]...)
92   $(dec,<value>[,value]...)
93   $(dec_hex,<value>[,value]...)
94   $(div,<value>[,value]...)
95   $(div_hex,<value>[,value]...)
96   $(inc,<value>[,value]...)
97   $(inc_hex,<value>[,value]...)
98   $(max,<value>[,value]...)
99   $(max_hex,<value>[,value]...)
100   $(min,<value>[,value]...)
101   $(min_hex,<value>[,value]...)
102   $(mod,<value>[,value]...)
103   $(mod_hex,<value>[,value]...)
104   $(mul,<value>[,value]...)
105   $(mul_hex,<value>[,value]...)
106   $(sub,<value>[,value]...)
107   $(sub_hex,<value>[,value]...)
108
109
110String functions
111****************
112
113The functions listed below can be used to modify string variables.
114
115.. code-block:: none
116
117   $(normalize_upper,<string>)
118   $(substring,<string>,<start>[,<stop>])
119
120
121Other functions
122***************
123
124Functions to perform specific operations, currently only a check if a shield
125name is specified.
126
127.. code-block:: none
128
129   $(shields_list_contains,<shield name>)
130
131
132Example Usage
133=============
134
135Assume that the devicetree for some board looks like this:
136
137.. code-block:: devicetree
138
139   {
140   	soc {
141   		#address-cells = <1>;
142   		#size-cells = <1>;
143
144   		spi0: spi@10014000 {
145   			compatible = "sifive,spi0";
146   			reg = <0x10014000 0x1000 0x20010000 0x3c0900>;
147   			reg-names = "control", "mem";
148   			...
149   		};
150   };
151
152The second entry in ``reg`` in ``spi@1001400`` (``<0x20010000 0x3c0900>``)
153corresponds to ``mem``, and has the address ``0x20010000``. This address can be
154inserted into Kconfig as follows:
155
156.. code-block:: kconfig
157
158   config FLASH_BASE_ADDRESS
159   	default $(dt_node_reg_addr_hex,/soc/spi@1001400,1)
160
161After preprocessor expansion, this turns into the definition below:
162
163.. code-block:: kconfig
164
165   config FLASH_BASE_ADDRESS
166   	default 0x20010000
167