doc/releases/migration-guide-4.1.rst
:orphan:
.. See https://docs.zephyrproject.org/latest/releases/index.html#migration-guides for details of what is supposed to go into this document.
.. _migration_4.1:
Migration guide to Zephyr v4.1.0 ################################
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
Support for the build type feature which was deprecated in Zephyr 3.6 has been removed,
:ref:application-file-suffixes/:ref:sysbuild_file_suffixes has replaced this.
Sysbuild
SB_CONFIG_MCUBOOT_MODE_SWAP_WITHOUT_SCRATCH has been deprecated and replaced
with SB_CONFIG_MCUBOOT_MODE_SWAP_USING_MOVE, applications should be updated to select this
new symbol if they were selecting the old symbol.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
The k_pipe API has been reworked and the API used in CONFIG_PIPES is now deprecated.
The k_pipe API is enabled by default when CONFIG_MULTITHREADING is set.
Function renames and modifications:
.. list-table:: :header-rows: 1
k_pipe_put(..)k_pipe_write(..)min_xfer parameter (partial transfers based on thresholds are no longer supported)
bytes_written is now the return valuek_pipe_get(..)k_pipe_read(..)min_xfer parameter (partial transfers based on thresholds are no longer supported)
bytes_read is now the return valuek_pipe_flush(..) & k_pipe_buffer_flush(..)k_pipe_reset(..)k_pipe_alloc_init(..), k_pipe_cleanup(..)k_pipe_read_avail(..), k_pipe_write_avail(..)k_pipe_close(..)k_pipe_init(..) again. Note, all data in the pipe is available to readers until the
pipe is emptied.Security
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.
All nRF52-based boards will now default to soft (system) reset
instead of pin reset when flashing with west flash. If you want to keep
using pin reset on the nRF52 family of ICs you can use west flash --pinreset.
Erasing the external memory when programming a new firmware image with west flash on the nRF52 and nRF53 series now always correctly honors the
--erase flag (and its absence) both when using the nrfjprog and
nrfutil backends. Prior to this release, the nrjfprog backend would
always erase only the sectors of the external flash used by the new firmware,
and the nrfutil one would always erase the whole external flash.
CAN1 and USART1 have been disabled on the stm32f4_disco, because of
conflicting pinctrl on I2C1, which is now used to control the audio codec
connected to the audio jack output.
Devicetree
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.CONFIG_SOC_SERIES_RP2XXX is renamed to :kconfig:option:CONFIG_SOC_SERIES_RP2040.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.
ADC properties st,adc-sequencer and st,adc-clock-source now uses
string values instead of integer values.
Modules
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.
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
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.compatible from nxp,kinetis-adc12 to :dtcompatible:nxp,adc12.freqs_mhz to freqs-mhz.cg_reg to cg-reg.pll_ctrl_reg to pll-ctrl-reg.primary_source to primary-source.secondary_source to secondary-source.filter_count to filter-count.filter_period to filter-period.infineon,xmc4xxx-can-node devicetree property clock_div8 to
clock-div8 (:github:83782).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.
voltage_reference and power_down_mode
to voltage-reference and power-down-mode.79931)Deprecated eth_mcux driver was removed.
Silabs gecko ethernet changes:
location-phy_mdc to location-phy-mdc.location-phy_mdio to location-phy-mdio.location-rmii_refclk to location-phy-refclk.location-rmii_crs_dv to location-phy-crs-dv.location-rmii_txd0 to location-phy-txd0.location-rmii_txd1 to location-phy-txd1.location-rmii_tx_en to location-phy-tx-en.location-rmii_rxd0 to location-phy-rxd0.location-rmii_rxd1 to location-phy-rxd1.location-rmii_rx_er to location-phy-rx-er.location-phy_pwr_enable to location-phy-pwr-enable.location-phy_reset to location-phy-reset.location-phy_interrupt to location-phy-interrupt.pin_mask to pin-mask.pinmux_mask to pinmux-mask.vbatts_pins to vbatts-pins.bit_per_gpio to bit-per-gpio.off_val to off-val.on_val to on-val.compatible from ti,ads114s0x-gpio to :dtcompatible:ti,ads1x4s0x-gpio.num_locks to num-locks.compatible from nxp,imx-lpi2c to :dtcompatible:nxp,lpi2c.port_sel to ``port-sel```.fifo_depth to fifo-depth.max_curr_opt to max-curr-opt.`compatible from renesas,ra8-pwm to :dtcompatible:renesas,ra-pwm.All the functions in the ft8xx driver take an additional const struct *device parameter
to allow for multiple instances of the driver.
The exception to this is the functions and macros defined in the
:zephyr_file:include/zephyr/drivers/misc/ft8xx/ft8xx_reference_api.h file, which translate the
API to a single-instance model, compatible with the API defined in the FT8xx programming guide.
These functions have not been modified.
The :c:func:ft8xx_register_int function now takes an additional void *user_data parameter
to allow user-defined data to be passed to the interrupt handler.
Additionally, the signature of the ft8xx interrupt handler has changed to include the
void *user_data parameter.
compatible from nxp,kinetis-mpu to :dtcompatible:nxp,sysmpu and added
its corresponding binding.CPU_HAS_NXP_MPU to :kconfig:option:CPU_HAS_NXP_SYSMPU.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 <zephyr/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; }; }; };
compatible from nxp,kinetis-ftm-pwm to :dtcompatible:nxp,ftm-pwm.power_delay_ms to ``power-delay-ms```max_current_330 to max-current-330The :dtcompatible:we,wsen-pads driver has been renamed to
:dtcompatible:we,wsen-pads-2511020213301.
The Device Tree can be configured as follows:
.. code-block:: devicetree
&i2c0 { pads:pads-2511020213301@5d { compatible = "we,wsen-pads-2511020213301"; reg = <0x5d>; odr = < 10 >; interrupt-gpios = <&gpio1 1 GPIO_ACTIVE_HIGH>; }; };
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 >; }; };
The :dtcompatible:we,wsen-tids driver has been renamed to
:dtcompatible:we,wsen-tids-2521020222501.
The Device Tree can be configured as follows:
.. code-block:: devicetree
&i2c0 { tids:tids-2521020222501@3F { compatible = "we,wsen-tids-2521020222501"; reg = < 0x3F >; odr = < 25 >; interrupt-gpios = <&gpio1 1 GPIO_ACTIVE_LOW>; }; };
The :dtcompatible:invensense,icp10125 driver has been renamed to
:dtcompatible:invensense,icp101xx.
The Device Tree can be configured as follows:
.. code-block:: devicetree
&i2c0 { icp101xx:icp101xx@63 { compatible = "invensense,icp101xx"; reg = <0x63>; }; };
compatible from nxp,kinetis-lpuart to :dtcompatible:nxp,lpuart.silabs,usart-uart
and Series 0/1 silabs,gecko-usartcompatible from zephyr,gpio-steppers to :dtcompatible:zephyr,gpio-stepper.stepper_set_actual_position function to :c:func:stepper_set_reference_position.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.stepper_move function to :c:func:stepper_move_by.stepper_set_target_position function to :c:func:stepper_move_to.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.stepper_run.STEPPER_ADI_TMC_RAMP_GEN is now deprecated and is replaced with the new
:kconfig:option:STEPPER_ADI_TMC50XX_RAMP_GEN option.adi,tmc50xx stepper driver, use
:c:func:tmc50xx_stepper_set_max_velocity or :c:func:tmc50xx_stepper_set_ramp.en_spreadcycle to en-spreadcycle.i_scale_analog to i-scale-analog.index_optw to index-otpw.ìndex_step to index-step.internal_rsense to internal-rsense.lock_gconf to lock-gconf.mstep_reg_select to mstep-reg-select.pdn_disable to pdn-disable.poscmp_enable to poscmp-enable.test_mode to test-mode.compatible from nxp,imx-lpspi to :dtcompatible:nxp,lpspi.compatible from nxp,kinetis-dspi to :dtcompatible:nxp,dspi.compatible from silabs,gecko-spi-usart to :dtcompatible:silabs,usart-spi.compatible from silabs,gecko-spi-eusart to :dtcompatible:silabs,eusart-spi.compatible from nxp,kinetis-rtc to :dtcompatible:nxp,rtc.compatible from nxp,kinetis-ftm to :dtcompatible:nxp,ftm and relocate it
under dts/bindings/timer.ticks_us to ticks-us.phy_handle to phy-handle.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.
The video_pix_fmt_bpp() function was returning a byte count, this got replaced by
video_bits_per_pixel() which return a bit count. For instance, invocations such as
pitch = width * video_pix_fmt_bpp(pixfmt) needs to be replaced by an equivalent
pitch = width * video_bits_per_pixel(pixfmt) / BITS_PER_BYTE.
The :c:func:video_buffer_alloc and :c:func:video_buffer_aligned_alloc functions in the
video API now take an additional timeout parameter.
The :c:func:video_stream_start and :c:func:video_stream_stop driver APIs are now merged
into the new :c:func:video_set_stream driver API. The user APIs are however unchanged to
keep backward compatibility with downstream applications.
compatible from nxp,kinetis-wdog32 to :dtcompatible:nxp,wdog32.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
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.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 key representations are not backward compatible if images are built with TinyCrypt and
crypto libraries based on the PSA API. Mesh no longer stores the key values for those crypto
libraries. The crypto library stores the keys in the internal trusted storage.
If a provisioned device is going to update its image that was built with
the :kconfig:option:CONFIG_BT_MESH_USES_TINYCRYPT Kconfig option set on an image
that was built with :kconfig:option:CONFIG_BT_MESH_USES_MBEDTLS_PSA or
:kconfig:option:CONFIG_BT_MESH_USES_TFM_PSA without erasing the persistent area,
it should be unprovisioned first and reprovisioned after update again.
If the image is changed over Mesh DFU, use :c:enumerator:BT_MESH_DFU_EFFECT_UNPROV.
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.
The following Kconfig options are not longer automatically enabled by the LE Audio Kconfig
options and may need to be enabled manually (:github:81328):
CONFIG_BT_GATT_CLIENTCONFIG_BT_GATT_AUTO_DISCOVER_CCCCONFIG_BT_GATT_AUTO_UPDATE_MTUCONFIG_BT_EXT_ADVCONFIG_BT_PER_ADV_SYNCCONFIG_BT_ISO_BROADCASTERCONFIG_BT_ISO_SYNC_RECEIVERCONFIG_BT_PAC_SNKCONFIG_BT_PAC_SRCPACS 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)
Several services and service client (AICS, ASCS, CSIP, HAS, MCS, PACS, TBS, VCP and VOCS) now
depend on :kconfig:option:CONFIG_BT_SMP and may need to be explicitly enabled.
(:github:`84994``)
: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.
CONFIG_BT_DIS_MODEL and :kconfig:option:CONFIG_BT_DIS_MANUF have been
deprecated. Application developers should now use the
:kconfig:option:CONFIG_BT_DIS_MODEL_NUMBER_STR and
:kconfig:option:CONFIG_BT_DIS_MANUF_NAME_STR Kconfig options to set the string values in the
Model Number String and Manufacturer Name String characteristics that are part of the Device
Information Service (DIS).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.
An additional _res_fallback parameter has been added to the :c:macro:HTTP_SERVICE_DEFINE
and :c:macro:HTTPS_SERVICE_DEFINE macros, allowing a fallback resource to be served if no other
resources match the requested path. To retain the existing behaviour, NULL can be passed as the
additional parameter.
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.
CONFIG_NET_TC_SKIP_FOR_HIGH_PRIO was deprecated in favour of
:kconfig:option:CONFIG_NET_TC_TX_SKIP_FOR_HIGH_PRIO to avoid naming ambiguity.
Other Subsystems
CONFIG_MAX_FILES has been renamed to
:kconfig:option:CONFIG_EXT2_MAX_FILES.CONFIG_SMF and
:kconfig:option:CONFIG_SMF_ANCESTOR_SUPPORT are now required to be enabled to use the
hawkBit subsystem.The Kconfig :kconfig:option:CONFIG_MCUBOOT_BOOTLOADER_MODE_SWAP_WITHOUT_SCRATCH has been
deprecated and replaced with :kconfig:option:CONFIG_MCUBOOT_BOOTLOADER_MODE_SWAP_USING_MOVE,
applications should be updated to select this new symbol if they were selecting the old symbol.
The deprecated macro MGMT_CB_ERROR_RET has been removed.
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.select or imply.
Users must ensure that the depencies are enabled in their applications.
:kconfig:option:CONFIG_SECURE_STORAGE_ITS_STORE_IMPLEMENTATION_SETTINGS previously enabled NVS
and settings, which means the NVS settings backend would get used by default if ZMS wasn't
enabled. (:github:86181)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
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.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
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.