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

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.

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.

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

ADC

  • Renamed the compatible from nxp,kinetis-adc12 to 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:

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

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

Watchdog

Wi-Fi

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

  • 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

Bluetooth Audio

Bluetooth Classic

Bluetooth Host

Bluetooth Crypto

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.

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