1:orphan:
2
3.. _migration_4.1:
4
5Migration guide to Zephyr v4.1.0 (Working Draft)
6################################################
7
8This document describes the changes required when migrating your application from Zephyr v4.0.0 to
9Zephyr v4.1.0.
10
11Any other changes (not directly related to migrating applications) can be found in
12the :ref:`release notes<zephyr_4.1>`.
13
14.. contents::
15    :local:
16    :depth: 2
17
18Build System
19************
20
21BOSSA Runner
22============
23
24The ``bossac`` runner has been changed to no longer do a full erase by default when flashing. To
25perform a full erase, pass the ``--erase`` option when executing ``west flash``.
26
27Kernel
28******
29
30Security
31********
32
33* New options for stack canaries have been added, providing users with finer control over stack
34  protection. With this change, :kconfig:option:`CONFIG_STACK_CANARIES` no longer enables the
35  compiler option ``-fstack-protector-all``. Users who wish to use this option must now enable
36  :kconfig:option:`CONFIG_STACK_CANARIES_ALL`.
37
38Boards
39******
40
41* Shield ``mikroe_weather_click`` now supports both I2C and SPI interfaces. Users should select
42  the required configuration by using ``mikroe_weather_click_i2c`` or ``mikroe_weather_click_spi``
43  instead of ``mikroe_weather_click``.
44
45Devicetree
46**********
47
48* The :dtcompatible:`microchip,cap1203` driver has changed its compatible to
49  :dtcompatible:`microchip,cap12xx` and has been updated to support multiple
50  channels.
51  The number of available channels is derived from the length of the devicetree
52  array property ``input-codes``.
53  The :kconfig:option:`CONFIG_INPUT_CAP1203_POLL` has been removed:
54  If the devicetree property ``int-gpios`` is present, interrupt mode is used
55  otherwise, polling is used.
56  The :kconfig:option:`CONFIG_INPUT_CAP1203_PERIOD` has been replaced with
57  the devicetree property ``poll-interval-ms``.
58  In interrupt mode, the devicetree property ``repeat`` is supported.
59
60Raspberry Pi
61============
62
63* ``CONFIG_SOC_SERIES_RP2XXX`` is renamed to :kconfig:option:`CONFIG_SOC_SERIES_RP2040`.
64
65STM32
66=====
67
68* MCO clock source and prescaler are now exclusively configured by the DTS
69  as it was introduced earlier.
70  The Kconfig method for configuration is now removed.
71
72Modules
73*******
74
75Mbed TLS
76========
77
78* If a platform has a CSPRNG source available (i.e. :kconfig:option:`CONFIG_CSPRNG_ENABLED`
79  is set), then the Kconfig option :kconfig:option:`CONFIG_MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG`
80  is the default choice for random number source instead of
81  :kconfig:option:`CONFIG_MBEDTLS_PSA_CRYPTO_LEGACY_RNG`. This helps in reducing
82  ROM/RAM footprint of the Mbed TLS library.
83
84* The newly-added Kconfig option :kconfig:option:`CONFIG_MBEDTLS_PSA_KEY_SLOT_COUNT`
85  allows to specify the number of key slots available in the PSA Crypto core.
86  Previously this value was not explicitly set, so Mbed TLS's default value of
87  32 was used. The new Kconfig option defaults to 16 instead in order to find
88  a reasonable compromise between RAM consumption and most common use cases.
89  It can be further trimmed down to reduce RAM consumption if the final
90  application doesn't need that many key slots simultaneously.
91
92Trusted Firmware-M
93==================
94
95LVGL
96====
97
98* The config option :kconfig:option:`CONFIG_LV_Z_FLUSH_THREAD_PRIO` is now called
99  :kconfig:option:`CONFIG_LV_Z_FLUSH_THREAD_PRIORITY` and its value is now interpreted as an
100  absolute priority instead of a cooperative one.
101
102Device Drivers and Devicetree
103*****************************
104
105* Device driver APIs are placed into iterable sections (:github:`71773` and :github:`82102`) to
106  allow for runtime checking. See :ref:`device_driver_api` for more details.
107  The :c:macro:`DEVICE_API()` macro should be used by out-of-tree driver implementations for
108  all the upstream driver classes.
109
110* The :c:func:`video_buffer_alloc` and :c:func:`video_buffer_aligned_alloc` functions in the
111  video API now take an additional timeout parameter.
112
113ADC
114===
115
116* Renamed the ``compatible`` from ``nxp,kinetis-adc12`` to :dtcompatible:`nxp,adc12`.
117
118Controller Area Network (CAN)
119=============================
120
121Display
122=======
123
124* Displays using the MIPI DBI driver which set their MIPI DBI mode via the
125  ``mipi-mode`` property in devicetree should now use a string property of
126  the same name, like so:
127
128  .. code-block:: devicetree
129
130    /* Legacy display definition */
131
132    st7735r: st7735r@0 {
133        ...
134        mipi-mode = <MIPI_DBI_MODE_SPI_4WIRE>;
135        ...
136    };
137
138    /* New display definition */
139
140    st7735r: st7735r@0 {
141        ...
142        mipi-mode = "MIPI_DBI_MODE_SPI_4WIRE";
143        ...
144    };
145
146
147Enhanced Serial Peripheral Interface (eSPI)
148===========================================
149
150Entropy
151=======
152
153* BT HCI based entropy driver now directly sends the HCI command to parse random
154  data instead of waiting for BT connection to be ready. This is helpful on
155  platforms where the BT controller owns the HW random generator and the application
156  processor needs to get random data before BT is fully enabled.
157  (:github:`79931`)
158
159GNSS
160====
161
162I2C
163===
164
165* Renamed the ``compatible`` from ``nxp,imx-lpi2c`` to :dtcompatible:`nxp,lpi2c`.
166
167Input
168=====
169
170PWM
171===
172
173* Renamed the ``compatible`` from ``renesas,ra8-pwm`` to :dtcompatible:`renesas,ra-pwm`.
174
175Interrupt Controller
176====================
177
178LED Strip
179=========
180
181MMU/MPU
182=======
183
184* Renamed the ``compatible`` from ``nxp,kinetis-mpu`` to :dtcompatible:`nxp,sysmpu` and added
185  its corresponding binding.
186* Renamed the Kconfig option ``CPU_HAS_NXP_MPU`` to :kconfig:option:`CPU_HAS_NXP_SYSMPU`.
187
188Pin Control
189===========
190
191  * Renamed the ``compatible`` from ``nxp,kinetis-pinctrl`` to :dtcompatible:`nxp,port-pinctrl`.
192  * Renamed the ``compatible`` from ``nxp,kinetis-pinmux`` to :dtcompatible:`nxp,port-pinmux`.
193  * Silabs Series 2 devices now use a new pinctrl driver selected by
194    :dtcompatible:`silabs,dbus-pinctrl`. This driver allows the configuration of GPIO properties
195    through device tree, rather than having them hard-coded for each supported signal. It also
196    supports all possible digital bus signals by including a binding header such as
197    :zephyr_file:`include/zephyr/dt-bindings/pinctrl/silabs/xg24-pinctrl.h`.
198
199    Pinctrl should now be configured like this:
200
201    .. code-block:: devicetree
202
203      #include <dt-bindings/pinctrl/silabs/xg24-pinctrl.h>
204
205      &pinctrl {
206        i2c0_default: i2c0_default {
207          group0 {
208            /* Pin selection(s) using bindings included above */
209            pins = <I2C0_SDA_PD2>, <I2C0_SCL_PD3>;
210            /* Shared properties for the group of pins */
211            drive-open-drain;
212            bias-pull-up;
213          };
214        };
215      };
216
217
218PWM
219===
220
221* Renamed the ``compatible`` from ``nxp,kinetis-ftm-pwm`` to :dtcompatible:`nxp,ftm-pwm`.
222
223Sensors
224=======
225
226Serial
227======
228
229* Renamed the ``compatible`` from ``nxp,kinetis-lpuart`` to :dtcompatible:`nxp,lpuart`.
230
231Stepper
232=======
233
234  * Renamed the ``compatible`` from ``zephyr,gpio-steppers`` to :dtcompatible:`zephyr,gpio-stepper`.
235  * Renamed the ``stepper_set_actual_position`` function to :c:func:`stepper_set_reference_position`.
236  * Renamed the ``stepper_enable_constant_velocity_mode`` function to :c:func:`stepper_run`.
237  * Renamed the ``stepper_move`` function to :c:func:`stepper_move_by`.
238  * Renamed the ``stepper_set_target_position`` function to :c:func:`stepper_move_to`.
239  * The :kconfig:option:`STEPPER_ADI_TMC_RAMP_GEN` is now deprecated and is replaced with the new
240    :kconfig:option:`STEPPER_ADI_TMC5041_RAMP_GEN` option.
241
242SPI
243===
244
245* Renamed the ``compatible`` from ``nxp,imx-lpspi`` to :dtcompatible:`nxp,lpspi`.
246* Renamed the ``compatible`` from ``nxp,kinetis-dspi`` to :dtcompatible:`nxp,dspi`.
247
248Regulator
249=========
250
251RTC
252===
253
254* Renamed the ``compatible`` from ``nxp,kinetis-rtc`` to :dtcompatible:`nxp,rtc`.
255
256Timer
257=====
258
259* Renamed the ``compatible`` from ``nxp,kinetis-ftm`` to :dtcompatible:`nxp,ftm` and relocate it
260  under ``dts/bindings/timer``.
261
262Video
263=====
264
265* The :file:`include/zephyr/drivers/video-controls.h` got updated to have video controls IDs (CIDs)
266  matching the definitions in the Linux kernel file ``include/uapi/linux/v4l2-controls.h``.
267  In most cases, removing the category prefix is enough: ``VIDEO_CID_CAMERA_GAIN`` becomes
268  ``VIDEO_CID_GAIN``.
269  The new ``video-controls.h`` source now contains description of each control ID to help
270  disambiguating.
271
272Watchdog
273========
274
275Wi-Fi
276=====
277
278* Renamed the ``compatible`` from ``nxp,kinetis-wdog32`` to :dtcompatible:`nxp,wdog32`.
279
280* The config options :kconfig:option:`CONFIG_NXP_WIFI_BUILD_ONLY_MODE` and
281  :kconfig:option:`CONFIG_NRF_WIFI_BUILD_ONLY_MODE` are now unified under
282  :kconfig:option:`CONFIG_BUILD_ONLY_NO_BLOBS` making it a common entry point
283  for any vendor to enable builds without blobs.
284
285Bluetooth
286*********
287
288Bluetooth HCI
289=============
290
291* The :kconfig:option:`BT_CTLR` has been deprecated. A new :kconfig:option:`HAS_BT_CTLR` has been
292  introduced which should be selected by the respective link layer Kconfig options (e.g. a
293  HCI driver option, or the one for the upstream controller). It's recommended that all HCI drivers
294  for local link layers select the new option, since that opens up the possibility of indicating
295  build-time support for specific features, which e.g. the host stack can take advantage of.
296
297Bluetooth Mesh
298==============
299
300* Following the beginnig of the deprecation process for the TinyCrypt crypto
301  library, Kconfig symbol :kconfig:option:`CONFIG_BT_MESH_USES_TINYCRYPT` was
302  set as deprecated. Default option for platforms that do not support TF-M
303  is :kconfig:option:`CONFIG_BT_MESH_USES_MBEDTLS_PSA`.
304
305Bluetooth Audio
306===============
307
308* The following Kconfig options are not longer automatically enabled by the LE Audio Kconfig
309  options and may need to be enabled manually (:github:`81328`):
310
311    * :kconfig:option:`CONFIG_BT_GATT_CLIENT`
312    * :kconfig:option:`CONFIG_BT_GATT_AUTO_DISCOVER_CCC`
313    * :kconfig:option:`CONFIG_BT_GATT_AUTO_UPDATE_MTU`
314    * :kconfig:option:`CONFIG_BT_EXT_ADV`
315    * :kconfig:option:`CONFIG_BT_PER_ADV_SYNC`
316    * :kconfig:option:`CONFIG_BT_ISO_BROADCASTER`
317    * :kconfig:option:`CONFIG_BT_ISO_SYNC_RECEIVER`
318    * :kconfig:option:`CONFIG_BT_PAC_SNK`
319    * :kconfig:option:`CONFIG_BT_PAC_SRC`
320
321Bluetooth Classic
322=================
323
324Bluetooth Host
325==============
326
327* :kconfig:option:`CONFIG_BT_BUF_ACL_RX_COUNT` has been deprecated. The number of ACL RX buffers is
328  now computed internally and is equal to :kconfig:option:`CONFIG_BT_MAX_CONN` + 1. If an application
329  needs more buffers, it can use the new :kconfig:option:`CONFIG_BT_BUF_ACL_RX_COUNT_EXTRA` to add
330  additional ones.
331
332  e.g. if :kconfig:option:`CONFIG_BT_MAX_CONN` was ``3`` and
333  :kconfig:option:`CONFIG_BT_BUF_ACL_RX_COUNT` was ``7`` then
334  :kconfig:option:`CONFIG_BT_BUF_ACL_RX_COUNT_EXTRA` should be set to ``7 - (3 + 1) = 3``.
335
336  .. warning::
337
338   The default value of :kconfig:option:`CONFIG_BT_BUF_ACL_RX_COUNT` has been set to 0.
339
340* LE legacy pairing is no longer enabled by default since it's not secure. Leaving it enabled
341  makes a device vulnerable for downgrade attacks. If an application still needs to use LE legacy
342  pairing, it should disable :kconfig:option:`CONFIG_BT_SMP_SC_PAIR_ONLY` manually.
343
344Bluetooth Crypto
345================
346
347Networking
348**********
349
350* The Prometheus metric creation has changed as user does not need to have a separate
351  struct :c:struct:`prometheus_metric` any more. This means that the Prometheus macros
352  :c:macro:`PROMETHEUS_COUNTER_DEFINE`, :c:macro:`PROMETHEUS_GAUGE_DEFINE`,
353  :c:macro:`PROMETHEUS_HISTOGRAM_DEFINE` and :c:macro:`PROMETHEUS_SUMMARY_DEFINE`
354  prototypes have changed. (:github:`81712`)
355
356* The default subnet mask on newly added IPv4 addresses is now specified with
357  :kconfig:option:`CONFIG_NET_IPV4_DEFAULT_NETMASK` option instead of being left
358  empty. Applications can still specify a custom netmask for an address with
359  :c:func:`net_if_ipv4_set_netmask_by_addr` function if needed.
360
361* The HTTP server public API function signature for the :c:type:`http_resource_dynamic_cb_t` has
362  changed, the data is now passed in a :c:struct:`http_request_ctx` which holds the data, data
363  length and request header information. Request headers should be accessed via this parameter
364  rather than directly in the :c:struct:`http_client_ctx` to correctly handle concurrent requests
365  on different HTTP/2 streams.
366
367* The :kconfig:option:`CONFIG_NET_L2_OPENTHREAD` symbol no longer implies the
368  :kconfig:option:`CONFIG_NVS` Kconfig option. Platforms using OpenThread must explicitly enable
369  either the :kconfig:option:`CONFIG_NVS` or :kconfig:option:`CONFIG_ZMS` Kconfig option.
370
371Other Subsystems
372****************
373
374Flash map
375=========
376
377hawkBit
378=======
379
380MCUmgr
381======
382
383Modem
384=====
385
386LoRa
387====
388
389* The function :c:func:`lora_recv_async` and callback ``lora_recv_cb`` now include an
390  additional ``user_data`` parameter, which is a void pointer. This parameter can be used to reference
391  any user-defined data structure. To maintain the current behavior, set this parameter to ``NULL``.
392
393Architectures
394*************
395
396* Common
397
398  * ``_current`` is deprecated, used :c:func:`arch_current_thread` instead.
399
400* native/POSIX
401
402  * :kconfig:option:`CONFIG_NATIVE_APPLICATION` has been deprecated. Out-of-tree boards using this
403    option should migrate to the native_simulator runner (:github:`81232`).
404    For an example of how this was done with a board in-tree check :github:`61481`.
405  * For the native_sim target :kconfig:option:`CONFIG_NATIVE_SIM_NATIVE_POSIX_COMPAT` has been
406    switched to ``n`` by default, and this option has been deprecated. Ensure your code does not
407    use the :kconfig:option:`CONFIG_BOARD_NATIVE_POSIX` option anymore (:github:`81232`).
408
409* x86
410
411  * Kconfigs ``CONFIG_DISABLE_SSBD`` and ``CONFIG_ENABLE_EXTENDED_IBRS`` have been deprecated
412    since v3.7. These were removed.  Use :kconfig:option:`CONFIG_X86_DISABLE_SSBD` and
413    :kconfig:option:`CONFIG_X86_ENABLE_EXTENDED_IBRS` instead.
414