:orphan:

.. _migration_4.1:

Migration guide to Zephyr v4.1.0 (Working Draft)
################################################

This document describes the changes required when migrating your application from Zephyr v4.0.0 to
Zephyr v4.1.0.

Any other changes (not directly related to migrating applications) can be found in
the :ref:`release notes<zephyr_4.1>`.

.. contents::
    :local:
    :depth: 2

Build System
************

BOSSA Runner
============

The ``bossac`` runner has been changed to no longer do a full erase by default when flashing. To
perform a full erase, pass the ``--erase`` option when executing ``west flash``.

Kernel
******

Security
********

* New options for stack canaries have been added, providing users with finer control over stack
  protection. With this change, :kconfig:option:`CONFIG_STACK_CANARIES` no longer enables the
  compiler option ``-fstack-protector-all``. Users who wish to use this option must now enable
  :kconfig:option:`CONFIG_STACK_CANARIES_ALL`.

Boards
******

* Shield ``mikroe_weather_click`` now supports both I2C and SPI interfaces. Users should select
  the required configuration by using ``mikroe_weather_click_i2c`` or ``mikroe_weather_click_spi``
  instead of ``mikroe_weather_click``.

Devicetree
**********

* The :dtcompatible:`microchip,cap1203` driver has changed its compatible to
  :dtcompatible:`microchip,cap12xx` and has been updated to support multiple
  channels.
  The number of available channels is derived from the length of the devicetree
  array property ``input-codes``.
  The :kconfig:option:`CONFIG_INPUT_CAP1203_POLL` has been removed:
  If the devicetree property ``int-gpios`` is present, interrupt mode is used
  otherwise, polling is used.
  The :kconfig:option:`CONFIG_INPUT_CAP1203_PERIOD` has been replaced with
  the devicetree property ``poll-interval-ms``.
  In interrupt mode, the devicetree property ``repeat`` is supported.

Raspberry Pi
============

* ``CONFIG_SOC_SERIES_RP2XXX`` is renamed to :kconfig:option:`CONFIG_SOC_SERIES_RP2040`.

STM32
=====

* MCO clock source and prescaler are now exclusively configured by the DTS
  as it was introduced earlier.
  The Kconfig method for configuration is now removed.

Modules
*******

Mbed TLS
========

* If a platform has a CSPRNG source available (i.e. :kconfig:option:`CONFIG_CSPRNG_ENABLED`
  is set), then the Kconfig option :kconfig:option:`CONFIG_MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG`
  is the default choice for random number source instead of
  :kconfig:option:`CONFIG_MBEDTLS_PSA_CRYPTO_LEGACY_RNG`. This helps in reducing
  ROM/RAM footprint of the Mbed TLS library.

* The newly-added Kconfig option :kconfig:option:`CONFIG_MBEDTLS_PSA_KEY_SLOT_COUNT`
  allows to specify the number of key slots available in the PSA Crypto core.
  Previously this value was not explicitly set, so Mbed TLS's default value of
  32 was used. The new Kconfig option defaults to 16 instead in order to find
  a reasonable compromise between RAM consumption and most common use cases.
  It can be further trimmed down to reduce RAM consumption if the final
  application doesn't need that many key slots simultaneously.

Trusted Firmware-M
==================

LVGL
====

* The config option :kconfig:option:`CONFIG_LV_Z_FLUSH_THREAD_PRIO` is now called
  :kconfig:option:`CONFIG_LV_Z_FLUSH_THREAD_PRIORITY` and its value is now interpreted as an
  absolute priority instead of a cooperative one.

* The config option :kconfig:option:`CONFIG_LV_Z_VBD_CUSTOM_SECTION` is now called
  :kconfig:option:`CONFIG_LV_Z_VDB_CUSTOM_SECTION`.

Device Drivers and Devicetree
*****************************

* Device driver APIs are placed into iterable sections (:github:`71773` and :github:`82102`) to
  allow for runtime checking. See :ref:`device_driver_api` for more details.
  The :c:macro:`DEVICE_API()` macro should be used by out-of-tree driver implementations for
  all the upstream driver classes.

* The :c:func:`video_buffer_alloc` and :c:func:`video_buffer_aligned_alloc` functions in the
  video API now take an additional timeout parameter.

ADC
===

* Renamed the ``compatible`` from ``nxp,kinetis-adc12`` to :dtcompatible:`nxp,adc12`.

Counter
=======

* Renamed the devicetree property ``primary_source`` to ``primary-source``.
* Renamed the devicetree property ``secondary_source`` to ``secondary-source``.
* Renamed the devicetree property ``filter_count`` to ``filter-count``.
* Renamed the devicetree property ``filter_period`` to ``filter-period``.

Controller Area Network (CAN)
=============================

Display
=======

* Displays using the MIPI DBI driver which set their MIPI DBI mode via the
  ``mipi-mode`` property in devicetree should now use a string property of
  the same name, like so:

  .. code-block:: devicetree

    /* Legacy display definition */

    st7735r: st7735r@0 {
        ...
        mipi-mode = <MIPI_DBI_MODE_SPI_4WIRE>;
        ...
    };

    /* New display definition */

    st7735r: st7735r@0 {
        ...
        mipi-mode = "MIPI_DBI_MODE_SPI_4WIRE";
        ...
    };

* Renamed the devicetree propertys ``pclk_pol`` and ``data_cmd-gpios``
  to ``pclk-pol`` and ``data-cmd-gpios``.

DAC
===

* Renamed the devicetree properties ``voltage_reference`` and ``power_down_mode``
  to ``voltage-reference`` and ``power-down-mode``.

Enhanced Serial Peripheral Interface (eSPI)
===========================================

Entropy
=======

* BT HCI based entropy driver now directly sends the HCI command to parse random
  data instead of waiting for BT connection to be ready. This is helpful on
  platforms where the BT controller owns the HW random generator and the application
  processor needs to get random data before BT is fully enabled.
  (:github:`79931`)

GNSS
====

GPIO
====

* Renamed the device tree property ``pin_mask`` to ``pin-mask``.
* Renamed the device tree property ``pinmux_mask`` to ``pinmux-mask``.
* Renamed the device tree property ``vbatts_pins`` to ``vbatts-pins``.
* Renamed the device tree property ``bit_per_gpio`` to ``bit-per-gpio``.
* Renamed the device tree property ``off_val`` to ``off-val``.
* Renamed the device tree property ``on_val`` to ``on-val``.

I2C
===

* Renamed the ``compatible`` from ``nxp,imx-lpi2c`` to :dtcompatible:`nxp,lpi2c`.

I2S
===

* Renamed the device tree property from ``fifo_depth`` to ``fifo-depth``.

Input
=====

LED
===

* Renamed the device tree property ``max_curr_opt`` to ``max-curr-opt``.`

PWM
===

* Renamed the ``compatible`` from ``renesas,ra8-pwm`` to :dtcompatible:`renesas,ra-pwm`.

Interrupt Controller
====================

LED Strip
=========

MMU/MPU
=======

* Renamed the ``compatible`` from ``nxp,kinetis-mpu`` to :dtcompatible:`nxp,sysmpu` and added
  its corresponding binding.
* Renamed the Kconfig option ``CPU_HAS_NXP_MPU`` to :kconfig:option:`CPU_HAS_NXP_SYSMPU`.

Pin Control
===========

  * Renamed the ``compatible`` from ``nxp,kinetis-pinctrl`` to :dtcompatible:`nxp,port-pinctrl`.
  * Renamed the ``compatible`` from ``nxp,kinetis-pinmux`` to :dtcompatible:`nxp,port-pinmux`.
  * Silabs Series 2 devices now use a new pinctrl driver selected by
    :dtcompatible:`silabs,dbus-pinctrl`. This driver allows the configuration of GPIO properties
    through device tree, rather than having them hard-coded for each supported signal. It also
    supports all possible digital bus signals by including a binding header such as
    :zephyr_file:`include/zephyr/dt-bindings/pinctrl/silabs/xg24-pinctrl.h`.

    Pinctrl should now be configured like this:

    .. code-block:: devicetree

      #include <dt-bindings/pinctrl/silabs/xg24-pinctrl.h>

      &pinctrl {
        i2c0_default: i2c0_default {
          group0 {
            /* Pin selection(s) using bindings included above */
            pins = <I2C0_SDA_PD2>, <I2C0_SCL_PD3>;
            /* Shared properties for the group of pins */
            drive-open-drain;
            bias-pull-up;
          };
        };
      };


PWM
===

* Renamed the ``compatible`` from ``nxp,kinetis-ftm-pwm`` to :dtcompatible:`nxp,ftm-pwm`.

SDHC
====

* Renamed the device tree property from ``power_delay_ms`` to ``power-delay-ms```
* Renamed the device tree property from ``max_current_330`` to ``max-current-330``

Sensors
=======

  * The :dtcompatible:`we,wsen-pdus` driver has been renamed to
    :dtcompatible:`we,wsen-pdus-25131308XXXXX`.
    The Device Tree can be configured as follows:

    .. code-block:: devicetree

      &i2c0 {
        pdus:pdus-25131308XXXXX@78 {
          compatible = "we,wsen-pdus-25131308XXXXX";
          reg = < 0x78 >;
          sensor-type = < 4 >;
        };
      };

Serial
======

* Renamed the ``compatible`` from ``nxp,kinetis-lpuart`` to :dtcompatible:`nxp,lpuart`.
* Silabs Usart driver has been split for Series 2 :dtcompatible:`silabs,usart-uart`
  and  Series 0/1 ``silabs,gecko-usart``

Stepper
=======

  * Renamed the ``compatible`` from ``zephyr,gpio-steppers`` to :dtcompatible:`zephyr,gpio-stepper`.
  * Renamed the ``stepper_set_actual_position`` function to :c:func:`stepper_set_reference_position`.
  * Renamed the ``stepper_enable_constant_velocity_mode`` function to :c:func:`stepper_run`.
    The function does not take a velocity parameter anymore. Set the desired speed using the
    :c:func:`stepper_set_microstep_interval` function beforehand.
  * Renamed the ``stepper_move`` function to :c:func:`stepper_move_by`.
  * Renamed the ``stepper_set_target_position`` function to :c:func:`stepper_move_to`.
  * Renamed the ``stepper_set_max_velocity`` function to :c:func:`stepper_set_microstep_interval`.
    The function now takes the step interval in nanoseconds. This allows for a more precise control.
  * Deprecating setting max velocity via :c:func:`stepper_run`.
  * The :kconfig:option:`STEPPER_ADI_TMC_RAMP_GEN` is now deprecated and is replaced with the new
    :kconfig:option:`STEPPER_ADI_TMC5041_RAMP_GEN` option.
  * To control the velocity for :dtcompatible:`adi,tmc5041` stepper driver, use
    :c:func:`tmc5041_stepper_set_max_velocity` or :c:func:`tmc5041_stepper_set_ramp`.
  * Renamed the DeviceTree property ``en_spreadcycle`` to ``en-spreadcycle``.
  * Renamed the DeviceTree property ``i_scale_analog`` to ``i-scale-analog``.
  * Renamed the DeviceTree property ``index_optw`` to ``index-otpw``.
  * Renamed the DeviceTree property ``ìndex_step`` to ``index-step``.
  * Renamed the DeviceTree property ``internal_rsense`` to ``internal-rsense``.
  * Renamed the DeviceTree property ``lock_gconf`` to ``lock-gconf``.
  * Renamed the DeviceTree property ``mstep_reg_select`` to ``mstep-reg-select``.
  * Renamed the DeviceTree property ``pdn_disable`` to ``pdn-disable``.
  * Renamed the DeviceTree property ``poscmp_enable`` to ``poscmp-enable``.
  * Renamed the DeviceTree property ``test_mode`` to ``test-mode``.

SPI
===

* Renamed the ``compatible`` from ``nxp,imx-lpspi`` to :dtcompatible:`nxp,lpspi`.
* Renamed the ``compatible`` from ``nxp,kinetis-dspi`` to :dtcompatible:`nxp,dspi`.
* Renamed the ``compatible`` from ``silabs,gecko-spi-usart`` to :dtcompatible:`silabs,usart-spi`.
* Renamed the ``compatible`` from ``silabs,gecko-spi-eusart`` to :dtcompatible:`silabs,eusart-spi`.

Regulator
=========

RTC
===

* Renamed the ``compatible`` from ``nxp,kinetis-rtc`` to :dtcompatible:`nxp,rtc`.

Timer
=====

* Renamed the ``compatible`` from ``nxp,kinetis-ftm`` to :dtcompatible:`nxp,ftm` and relocate it
  under ``dts/bindings/timer``.

USB
===

* Renamed the devicetree property names ``phy_handle`` to ``phy-handle``.

Video
=====

* The :file:`include/zephyr/drivers/video-controls.h` got updated to have video controls IDs (CIDs)
  matching the definitions in the Linux kernel file ``include/uapi/linux/v4l2-controls.h``.
  In most cases, removing the category prefix is enough: ``VIDEO_CID_CAMERA_GAIN`` becomes
  ``VIDEO_CID_GAIN``.
  The new ``video-controls.h`` source now contains description of each control ID to help
  disambiguating.

Watchdog
========

Wi-Fi
=====

* Renamed the ``compatible`` from ``nxp,kinetis-wdog32`` to :dtcompatible:`nxp,wdog32`.

* The config options :kconfig:option:`CONFIG_NXP_WIFI_BUILD_ONLY_MODE` and
  :kconfig:option:`CONFIG_NRF_WIFI_BUILD_ONLY_MODE` are now unified under
  :kconfig:option:`CONFIG_BUILD_ONLY_NO_BLOBS` making it a common entry point
  for any vendor to enable builds without blobs.

Bluetooth
*********

Bluetooth HCI
=============

* The :kconfig:option:`BT_CTLR` has been deprecated. A new :kconfig:option:`HAS_BT_CTLR` has been
  introduced which should be selected by the respective link layer Kconfig options (e.g. a
  HCI driver option, or the one for the upstream controller). It's recommended that all HCI drivers
  for local link layers select the new option, since that opens up the possibility of indicating
  build-time support for specific features, which e.g. the host stack can take advantage of.

Bluetooth Mesh
==============

* Following the beginnig of the deprecation process for the TinyCrypt crypto
  library, Kconfig symbol :kconfig:option:`CONFIG_BT_MESH_USES_TINYCRYPT` was
  set as deprecated. Default option for platforms that do not support TF-M
  is :kconfig:option:`CONFIG_BT_MESH_USES_MBEDTLS_PSA`.

* Mesh explicitly depends on the Secure Storage subsystem if storing into
  non-volatile memory (:kconfig:option:`CONFIG_BT_SETTINGS`) is enabled and
  Mbed TLS library (:kconfig:option:`CONFIG_BT_MESH_USES_MBEDTLS_PSA`) is used.
  Applications should be built with :kconfig:option:`CONFIG_SECURE_STORAGE` enabled.

Bluetooth Audio
===============

* The following Kconfig options are not longer automatically enabled by the LE Audio Kconfig
  options and may need to be enabled manually (:github:`81328`):

    * :kconfig:option:`CONFIG_BT_GATT_CLIENT`
    * :kconfig:option:`CONFIG_BT_GATT_AUTO_DISCOVER_CCC`
    * :kconfig:option:`CONFIG_BT_GATT_AUTO_UPDATE_MTU`
    * :kconfig:option:`CONFIG_BT_EXT_ADV`
    * :kconfig:option:`CONFIG_BT_PER_ADV_SYNC`
    * :kconfig:option:`CONFIG_BT_ISO_BROADCASTER`
    * :kconfig:option:`CONFIG_BT_ISO_SYNC_RECEIVER`
    * :kconfig:option:`CONFIG_BT_PAC_SNK`
    * :kconfig:option:`CONFIG_BT_PAC_SRC`

* PACS have been changed to support dynamic, runtime configuration. This means that PACS now has
  to be registered with :c:func:`bt_pacs_register` before it can be used. In addition,
  :c:func:`bt_pacs_register` also have to be called before :c:func:`bt_ascs_register` can be
  be called. All Kconfig options still remain. Runtime configuration cannot override a disabled
  Kconfig option. (:github:`83730`)

Bluetooth Classic
=================

Bluetooth Host
==============

* :kconfig:option:`CONFIG_BT_BUF_ACL_RX_COUNT` has been deprecated. The number of ACL RX buffers is
  now computed internally and is equal to :kconfig:option:`CONFIG_BT_MAX_CONN` + 1. If an application
  needs more buffers, it can use the new :kconfig:option:`CONFIG_BT_BUF_ACL_RX_COUNT_EXTRA` to add
  additional ones.

  e.g. if :kconfig:option:`CONFIG_BT_MAX_CONN` was ``3`` and
  :kconfig:option:`CONFIG_BT_BUF_ACL_RX_COUNT` was ``7`` then
  :kconfig:option:`CONFIG_BT_BUF_ACL_RX_COUNT_EXTRA` should be set to ``7 - (3 + 1) = 3``.

  .. warning::

   The default value of :kconfig:option:`CONFIG_BT_BUF_ACL_RX_COUNT` has been set to 0.

* LE legacy pairing is no longer enabled by default since it's not secure. Leaving it enabled
  makes a device vulnerable for downgrade attacks. If an application still needs to use LE legacy
  pairing, it should disable :kconfig:option:`CONFIG_BT_SMP_SC_PAIR_ONLY` manually.

* The prompt for :kconfig:option:`CONFIG_BT_ECC` has been removed, since it only offers an internal
  API, meaning internal users should explicitly select it in their respective Kconfig options.

Bluetooth Crypto
================

Networking
**********

* The Prometheus metric creation has changed as user does not need to have a separate
  struct :c:struct:`prometheus_metric` any more. This means that the Prometheus macros
  :c:macro:`PROMETHEUS_COUNTER_DEFINE`, :c:macro:`PROMETHEUS_GAUGE_DEFINE`,
  :c:macro:`PROMETHEUS_HISTOGRAM_DEFINE` and :c:macro:`PROMETHEUS_SUMMARY_DEFINE`
  prototypes have changed. (:github:`81712`)

* The default subnet mask on newly added IPv4 addresses is now specified with
  :kconfig:option:`CONFIG_NET_IPV4_DEFAULT_NETMASK` option instead of being left
  empty. Applications can still specify a custom netmask for an address with
  :c:func:`net_if_ipv4_set_netmask_by_addr` function if needed.

* The HTTP server public API function signature for the :c:type:`http_resource_dynamic_cb_t` has
  changed, the data is now passed in a :c:struct:`http_request_ctx` which holds the data, data
  length and request header information. Request headers should be accessed via this parameter
  rather than directly in the :c:struct:`http_client_ctx` to correctly handle concurrent requests
  on different HTTP/2 streams.

* The HTTP server public API function signature for the :c:type:`http_resource_websocket_cb_t` has
  changed, a :c:struct:`http_request_ctx` parameter has been added. The application may use this to
  access the request headers of the HTTP upgrade request, which may be useful in deciding whether
  to accept or reject a websocket connection.

* The :kconfig:option:`CONFIG_NET_L2_OPENTHREAD` symbol no longer implies the
  :kconfig:option:`CONFIG_NVS` Kconfig option. Platforms using OpenThread must explicitly enable
  either the :kconfig:option:`CONFIG_NVS` or :kconfig:option:`CONFIG_ZMS` Kconfig option.

Other Subsystems
****************

Flash map
=========

Filesystem
==========

* The EXT2 Kconfig symbol ``CONFIG_MAX_FILES`` has been renamed to
  :kconfig:option:`CONFIG_EXT2_MAX_FILES`.

hawkBit
=======

MCUmgr
======

Modem
=====

LoRa
====

* The function :c:func:`lora_recv_async` and callback ``lora_recv_cb`` now include an
  additional ``user_data`` parameter, which is a void pointer. This parameter can be used to reference
  any user-defined data structure. To maintain the current behavior, set this parameter to ``NULL``.

Stream Flash
============

* The function :c:func:`stream_flash_init` no longer does auto-detection of device size
  when ``size`` parameter is set to 0 and will return error in such case. User is now
  required to explicitly provide device size. Issue :github:`71042` provides rationale
  for the change.

Architectures
*************

* native/POSIX

  * :kconfig:option:`CONFIG_NATIVE_APPLICATION` has been deprecated. Out-of-tree boards using this
    option should migrate to the native_simulator runner (:github:`81232`).
    For an example of how this was done with a board in-tree check :github:`61481`.
  * For the native_sim target :kconfig:option:`CONFIG_NATIVE_SIM_NATIVE_POSIX_COMPAT` has been
    switched to ``n`` by default, and this option has been deprecated. Ensure your code does not
    use the :kconfig:option:`CONFIG_BOARD_NATIVE_POSIX` option anymore (:github:`81232`).

* x86

  * Kconfigs ``CONFIG_DISABLE_SSBD`` and ``CONFIG_ENABLE_EXTENDED_IBRS`` have been deprecated
    since v3.7. These were removed.  Use :kconfig:option:`CONFIG_X86_DISABLE_SSBD` and
    :kconfig:option:`CONFIG_X86_ENABLE_EXTENDED_IBRS` instead.
