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 release notes.

Build System

  • Support for the build type feature which was deprecated in Zephyr 3.6 has been removed, File Suffixes/Sysbuild file suffix support has replaced this.

  • Sysbuild

    • The Kconfig 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.

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

k_pipe API

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:

Old API

New API

Changes

k_pipe_put(..)

k_pipe_write(..)

Removed min_xfer parameter (partial transfers based on thresholds are no longer supported) bytes_written is now the return value

k_pipe_get(..)

k_pipe_read(..)

Removed min_xfer parameter (partial transfers based on thresholds are no longer supported) bytes_read is now the return value

k_pipe_flush(..) & k_pipe_buffer_flush(..)

k_pipe_reset(..)

Reset the pipe, discarding all data in the pipe, non blocking.

k_pipe_alloc_init(..), k_pipe_cleanup(..)

Removed

Dynamic allocation of pipes is no longer supported

k_pipe_read_avail(..), k_pipe_write_avail(..)

Removed

Querying the number of bytes in the pipe is no longer supported

None

k_pipe_close(..)

Close a pipe, waking up all pending readers and writers with an error code. No further reading or writing is allowed on the pipe. The pipe can be re-opened by calling k_pipe_init(..) again. Note, all data in the pipe is available to readers until the pipe is emptied.

Security

  • New options for stack canaries have been added, providing users with finer control over stack protection. With this change, CONFIG_STACK_CANARIES no longer enables the compiler option -fstack-protector-all. Users who wish to use this option must now enable 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

  • The microchip,cap1203 driver has changed its compatible to 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 CONFIG_INPUT_CAP1203_POLL has been removed: If the devicetree property int-gpios is present, interrupt mode is used otherwise, polling is used. The 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

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.

  • ADC properties st,adc-sequencer and st,adc-clock-source now uses string values instead of integer values.

Modules

Mbed TLS

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

  • The newly-added 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

Device Drivers and Devicetree

  • Device driver APIs are placed into iterable sections (GitHub #71773 and GitHub #82102) to allow for runtime checking. See Driver APIs for more details. The DEVICE_API() macro should be used by out-of-tree driver implementations for all the upstream driver classes.

ADC

  • Renamed the compatible from nxp,kinetis-adc12 to nxp,adc12.

Clock

  • Renamed the devicetree property freqs_mhz to freqs-mhz.

  • Renamed the devicetree property cg_reg to cg-reg.

  • Renamed the devicetree property pll_ctrl_reg to pll-ctrl-reg.

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:

    /* 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)

Ethernet

  • Deprecated eth_mcux driver was removed.

  • Silabs gecko ethernet changes:

    • Renamed the devicetree property location-phy_mdc to location-phy-mdc.

    • Renamed the devicetree property location-phy_mdio to location-phy-mdio.

    • Renamed the devicetree property location-rmii_refclk to location-phy-refclk.

    • Renamed the devicetree property location-rmii_crs_dv to location-phy-crs-dv.

    • Renamed the devicetree property location-rmii_txd0 to location-phy-txd0.

    • Renamed the devicetree property location-rmii_txd1 to location-phy-txd1.

    • Renamed the devicetree property location-rmii_tx_en to location-phy-tx-en.

    • Renamed the devicetree property location-rmii_rxd0 to location-phy-rxd0.

    • Renamed the devicetree property location-rmii_rxd1 to location-phy-rxd1.

    • Renamed the devicetree property location-rmii_rx_er to location-phy-rx-er.

    • Renamed the devicetree property location-phy_pwr_enable to location-phy-pwr-enable.

    • Renamed the devicetree property location-phy_reset to location-phy-reset.

    • Renamed the devicetree property location-phy_interrupt to location-phy-interrupt.

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.

  • Renamed the compatible from ti,ads114s0x-gpio to ti,ads1x4s0x-gpio.

HWSPINLOCK

  • Renamed the DeviceTree property num_locks to num-locks.

I2C

  • Renamed the compatible from nxp,imx-lpi2c to nxp,lpi2c.

  • Renamed the device tree property port_sel to port-sel`.

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

Interrupt Controller

LED Strip

Misc

  • 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 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 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.

MMU/MPU

  • Renamed the compatible from nxp,kinetis-mpu to nxp,sysmpu and added its corresponding binding.

  • Renamed the Kconfig option CPU_HAS_NXP_MPU to CPU_HAS_NXP_SYSMPU.

Pin Control

  • Renamed the compatible from nxp,kinetis-pinctrl to nxp,port-pinctrl.

  • Renamed the compatible from nxp,kinetis-pinmux to nxp,port-pinmux.

  • Silabs Series 2 devices now use a new pinctrl driver selected by 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 include/zephyr/dt-bindings/pinctrl/silabs/xg24-pinctrl.h.

    Pinctrl should now be configured like this:

    #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 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 we,wsen-pads driver has been renamed to we,wsen-pads-2511020213301. The Device Tree can be configured as follows:

    &i2c0 {
  pads:pads-2511020213301@5d {
    compatible = "we,wsen-pads-2511020213301";
    reg = <0x5d>;
    odr = < 10 >;
    interrupt-gpios = <&gpio1 1 GPIO_ACTIVE_HIGH>;
  };
};

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

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

  • The we,wsen-tids driver has been renamed to we,wsen-tids-2521020222501. The Device Tree can be configured as follows:

    &i2c0 {
  tids:tids-2521020222501@3F {
    compatible = "we,wsen-tids-2521020222501";
    reg = < 0x3F >;
    odr = < 25 >;
    interrupt-gpios = <&gpio1 1 GPIO_ACTIVE_LOW>;
  };
};

  • The invensense,icp10125 driver has been renamed to invensense,icp101xx. The Device Tree can be configured as follows:

    &i2c0 {
  icp101xx:icp101xx@63 {
     compatible = "invensense,icp101xx";
     reg = <0x63>;
  };
};

Serial

  • Renamed the compatible from nxp,kinetis-lpuart to nxp,lpuart.

  • Silabs Usart driver has been split for Series 2 silabs,usart-uart and Series 0/1 silabs,gecko-usart

Stepper

  • Renamed the compatible from zephyr,gpio-steppers to zephyr,gpio-stepper.

  • Renamed the stepper_set_actual_position function to stepper_set_reference_position().

  • Renamed the stepper_enable_constant_velocity_mode function to stepper_run(). The function does not take a velocity parameter anymore. Set the desired speed using the stepper_set_microstep_interval() function beforehand.

  • Renamed the stepper_move function to stepper_move_by().

  • Renamed the stepper_set_target_position function to stepper_move_to().

  • Renamed the stepper_set_max_velocity function to 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 stepper_run().

  • The STEPPER_ADI_TMC_RAMP_GEN is now deprecated and is replaced with the new STEPPER_ADI_TMC50XX_RAMP_GEN option.

  • Renamed tmc5041 stepper driver to tmc50xx.

  • To control the velocity for adi,tmc50xx stepper driver, use tmc50xx_stepper_set_max_velocity() or tmc50xx_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 nxp,lpspi.

  • Renamed the compatible from nxp,kinetis-dspi to nxp,dspi.

  • Renamed the compatible from silabs,gecko-spi-usart to silabs,usart-spi.

  • Renamed the compatible from silabs,gecko-spi-eusart to silabs,eusart-spi.

Regulator

RTC

  • Renamed the compatible from nxp,kinetis-rtc to nxp,rtc.

Timer

  • Renamed the compatible from nxp,kinetis-ftm to nxp,ftm and relocate it under dts/bindings/timer.

  • Renamed the device tree property from ticks_us to ticks-us.

USB

  • Renamed the devicetree property names phy_handle to phy-handle.

Video

  • The 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 video_buffer_alloc() and video_buffer_aligned_alloc() functions in the video API now take an additional timeout parameter.

  • The video_stream_start() and video_stream_stop() driver APIs are now merged into the new video_set_stream() driver API. The user APIs are however unchanged to keep backward compatibility with downstream applications.

Watchdog

  • Renamed the compatible from nxp,kinetis-wdog32 to nxp,wdog32.

Wi-Fi

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

Bluetooth

Bluetooth HCI

  • The BT_CTLR has been deprecated. A new 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 CONFIG_BT_MESH_USES_TINYCRYPT was set as deprecated. Default option for platforms that do not support TF-M is 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 CONFIG_BT_MESH_USES_TINYCRYPT Kconfig option set on an image that was built with CONFIG_BT_MESH_USES_MBEDTLS_PSA or 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 BT_MESH_DFU_EFFECT_UNPROV.

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

Bluetooth Audio

Bluetooth Classic

Bluetooth Host

Bluetooth Crypto

Bluetooth Services

Networking

Other Subsystems

Flash map

Filesystem

hawkBit

MCUmgr

Modem

LoRa

  • The function 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.

Secure Storage

  • Store backends no longer automatically enable their dependencies through select or imply. Users must ensure that the depencies are enabled in their applications. 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

  • The function 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.

    • For the native_sim target 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 CONFIG_BOARD_NATIVE_POSIX option anymore (GitHub #81232).

  • x86