Migration guide to Zephyr v4.2.0 (Working Draft)

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

Any other changes (not directly related to migrating applications) can be found in the release notes.

Common

  • The minimum required Python version is now 3.12 (from 3.10).

Build System

Kernel

Boards

  • All boards based on Nordic ICs that used the nrfjprog Nordic command-line tool for flashing by default have been modified to instead default to the new nRF Util (nrfutil) tool. This means that you may need to install nRF Util or, if you prefer to continue using nrfjprog, you can do so by invoking west while specfying the runner: west flash -r nrfjprog. The full documentation for nRF Util can be found here.

  • All boards based on a Nordic IC of the nRF54L series now default to not erasing any part of the internal storage when flashing. If you’d like to revert to the previous default of erasing the pages that will be written to by the firmware to be flashed you can set the new --erase-mode command-line switch when invoking west flash to ranges. Note that RRAM on nRF54L devices is not physically paged, and paging is only artificially provided, with a page size of 4096 bytes, for an easier transition of nRF52 software to nRF54L devices.

  • The config option CONFIG_NATIVE_POSIX_SLOWDOWN_TO_REAL_TIME has been deprecated in favor of CONFIG_NATIVE_SIM_SLOWDOWN_TO_REAL_TIME.

  • The DT binding zephyr,native-posix-cpu has been deprecated in favor of zephyr,native-sim-cpu.

  • Zephyr now supports version 1.11.3 of the NEORV32. NEORV32 processor (SoC) implementations need to be updated to this version to be compatible with Zephyr v4.2.0.

  • The NEORV32 now targets NEORV32 processor (SoC) templates via board variants. The old neorv32 board target is now named neorv32/neorv32/up5kdemo.

  • arduino_uno_r4_minima, arduino_uno_r4_wifi, and mikroe_clicker_ra4m1 have migrated to new FSP-based configurations. While there are no major functional changes, the device tree structure has been significantly revised. The following device tree bindings are now removed: renesas,ra-gpio, renesas,ra-uart-sci, renesas,ra-pinctrl, renesas,ra-clock-generation-circuit, and renesas,ra-interrupt-controller-unit. Instead, use the following replacements: - renesas,ra-gpio-ioport - renesas,ra-sci-uart - renesas,ra-pinctrl-pfs - renesas,ra-cgc-pclk-block

  • Nucleo WBA52CG board (nucleo_wba52cg) is not supported anymore since it is NRND (Not Recommended for New Design) and it is not supported anymore in the STM32CubeWBA from version 1.1.0 (July 2023). The migration to Nucleo WBA55CG (nucleo_wba55cg) is recommended and it could be done without any change.

  • Espressif boards esp32_devkitc_wroom and esp32_devkitc_wrover shared almost identical features. The differences are covered by the Kconfig options so both boards were merged into esp32_devkitc.

  • STM32 boards should now add OpenOCD programming support by including openocd-stm32.board.cmake instead of openocd.board.cmake. The openocd-stm32.board.cmake file extends the default OpenOCD runner with manufacturer-specific configuration like STM32 mass erase commands.

Device Drivers and Devicetree

Devicetree

  • Many of the vendor-specific and arch-specific files that were in dts/common have been moved to more specific locations. Therefore, any dts files which #include <common/some_file.dtsi> a file from in the zephyr tree will need to be changed to just #include <some_file.dtsi>.

  • Silicon Labs SoC-level dts files for Series 2 have been reorganized in subdirectories per device superfamily. Therefore, any dts files for boards that use Series 2 SoCs will need to change their include from #include <silabs/some_soc.dtsi> to #include <silabs/xg2[1-9]/some_soc.dtsi>.

  • The DT_ENUM_HAS_VALUE and DT_INST_ENUM_HAS_VALUE macros are now checking all values, when used on an array, not just the first one.

  • Property names in devicetree and bindings use hyphens(-) as separators, and replacing all previously used underscores(_). For local code, you can migrate property names in bindings to use hyphens by running the scripts/utils/migrate_bindings_style.py script.

DAI

  • Renamed the devicetree property dai_id to dai-id.

  • Renamed the devicetree property afe_name to afe-name.

  • Renamed the devicetree property agent_disable to agent-disable.

  • Renamed the devicetree property ch_num to ch-num.

  • Renamed the devicetree property mono_invert to mono-invert.

  • Renamed the devicetree property quad_ch to quad-ch.

  • Renamed the devicetree property int_odd to int-odd.

DMA

  • Renamed the devicetree property nxp,a_on to nxp,a-on.

  • Renamed the devicetree property dma_channels to dma-channels.

  • The binding files for Xilinx DMA controllers have been renamed to use the proper vendor prefix (xlnx instead of xilinx) and to match their compatible string.

Regulator

  • nordic,npm1300-regulator BUCK and LDO node GPIO properties are now specified as an integer array without a GPIO controller, removing the requirement for a nordic,npm1300-gpio node to be present and enabled for GPIO control of the output rails. For example, enable-gpios = <&pmic_gpios 3 GPIO_ACTIVE_LOW>; is now specified as enable-gpio-config = <3 GPIO_ACTIVE_LOW>;.

Counter

Entropy

Eeprom

  • ti,tmp116-eeprom has been renamed to ti,tmp11x-eeprom because it supports both tmp117 and tmp119.

Ethernet

Enhanced Serial Peripheral Interface (eSPI)

  • Renamed the devicetree property io_girq to io-girq.

  • Renamed the devicetree property vw_girqs to vw-girqs.

  • Renamed the devicetree property pc_girq to pc-girq.

  • Renamed the devicetree property poll_timeout to poll-timeout.

  • Renamed the devicetree property poll_interval to poll-interval.

  • Renamed the devicetree property consec_rd_timeout to consec-rd-timeout.

  • Renamed the devicetree property sus_chk_delay to sus-chk-delay.

  • Renamed the devicetree property sus_rsm_interval to sus-rsm-interval.

GPIO

  • To support the RP2350B, which has many pins, the Raspberry Pi-GPIO configuration has been changed. The previous role of raspberrypi,rpi-gpio has been migrated to raspberrypi,rpi-gpio-port, and raspberrypi,rpi-gpio is now left as a placeholder and mapper. The labels have also been changed along, so no changes are necessary for regular use.

  • arduino-nano-header-r3 is renamed to arduino-nano-header. Because the R3 comes from the Arduino UNO R3, which has changed the connector from the former version, and is unrelated to the Arduino Nano.

I2S

  • The nxp,mcux-i2s driver added property mclk-output. Set this property to

  • configure the MCLK signal as an output. Older driver versions used the macro

  • I2S_OPT_BIT_CLK_SLAVE to configure the MCLK signal direction. (GitHub #88554)

Sensors

  • ltr vendor prefix has been renamed to liteon, and with it the ltr,f216a name has been replaced by liteon,ltrf216a. The choice DT_HAS_LTR_F216A_ENABLED has been replaced with DT_HAS_LITEON_LTRF216A_ENABLED (GitHub #85453)

  • ti,tmp116 has been renamed to ti,tmp11x because it supports tmp116, tmp117 and tmp119.

  • meas,ms5837 has been replaced by meas,ms5837-30ba and meas,ms5837-02ba. In order to use one of the two variants, the status property needs to be used as well.

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

    &i2c0 {
  itds:itds-2533020201601@19 {
    compatible = "we,wsen-itds-2533020201601";
    reg = <0x19>;
    odr = "400";
    op-mode = "high-perf";
    power-mode = "normal";
    events-interrupt-gpios = <&gpio1 1 GPIO_ACTIVE_HIGH>;
    drdy-interrupt-gpios = < &gpio1 2 GPIO_ACTIVE_HIGH >;
  };
};

  • The binding file for raspberrypi,pico-temp.yaml has been renamed to have a name matching the compatible string.

Serial

Timer

  • native_posix_timer has been renamed native_sim_timer, and so its kconfig option CONFIG_NATIVE_POSIX_TIMER has been deprecated in favor of CONFIG_NATIVE_SIM_TIMER, (GitHub #86612).

  • andestech,machine-timer, neorv32-machine-timer, telink,machine-timer, lowrisc,machine-timer, niosv-machine-timer, and scr,machine-timer have been unified under riscv,machine-timer.

    The addresses of both MTIME and MTIMECMP registers must now be explicitly specified using the reg and reg-names properties. The reg-names property is now required, and must list names corresponding one-to-one with each entry in reg. (GitHub #84175 and GitHub #89847)

    Example:

    mtimer: timer@d1000000 {
    compatible = "riscv,machine-timer";
    interrupts-extended = <&cpu0_intc 7>;
    reg = <0xd1000000 0x8
           0xd1000008 0x8>;
    reg-names = "mtime", "mtimecmp";
};

Modem

Flash

  • Renamed the file from flash_hp_ra.h to soc_flash_renesas_ra_hp.h.

  • Renamed the file from flash_hp_ra.c to soc_flash_renesas_ra_hp.c.

  • Renamed the file from flash_hp_ra_ex_op.c to soc_flash_renesas_ra_hp_ex_op.c.

  • The Flash HP Renesas RA dual bank mode Kconfig symbol CONFIG_DUAL_BANK_MODE has been removed.

  • The Flash HP Renesas RA Kconfig symbol CONFIG_RA_FLASH_HP has been renamed to CONFIG_SOC_FLASH_RENESAS_RA_HP.

  • The Flash HP Renesas RA write protect Kconfig symbol CONFIG_FLASH_RA_WRITE_PROTECT has been renamed to CONFIG_FLASH_RENESAS_RA_HP_WRITE_PROTECT.

  • Separate the file renesas,ra-nv-flash.yaml into 2 files renesas,ra-nv-code-flash.yaml and renesas,ra-nv-data-flash.yaml.

  • Separate the compatible from renesas,ra-nv-flash to renesas,ra-nv-code-flash.yaml and renesas,ra-nv-data-flash.yaml.

Stepper

Misc

  • Moved file drivers/memc/memc_nxp_flexram.h to include/zephyr/drivers/misc/flexram/nxp_flexram.h so that the file can be included using <zephyr/drivers/misc/flexram/nxp_flexram.h>. Modification to CMakeList.txt to use include this driver is no longer required.

  • All memc_flexram_* namespaced things including kconfigs and C API have been changed to just flexram_*.

Bluetooth

Bluetooth Audio

Bluetooth HCI

  • The buffer types passing through the HCI driver interface are now indicated as H:4 encoded prefix bytes as part of the buffer payload itself. The bt_buf_set_type() and bt_buf_get_type() functions have been deprecated, but are still usable, with the exception that they can only be called once per buffer.

Bluetooth Host

Bluetooth Classic

  • The parameters of HFP AG callback sco_disconnected of the struct bt_hfp_ag_cb have been changed to SCO connection object struct bt_conn *sco_conn and the disconnection reason of the SCO connection uint8_t reason.

Networking

  • The struct net_linkaddr_storage has been renamed to struct net_linkaddr and the old struct net_linkaddr has been removed. The struct net_linkaddr now contains space to store the link address instead of having pointer that point to the link address. This avoids possible dangling pointers when cloning struct net_pkt. This will increase the size of struct net_pkt by 4 octets for IEEE 802.15.4, but there is no size increase for other network technologies like Ethernet. Note that any code that is using struct net_linkaddr directly, and which has checks like if (lladdr->addr == NULL), will no longer work as expected (because the addr is not a pointer) and must be changed to if (lladdr->len == 0) if the code wants to check that the link address is not set.

  • TLS credential type TLS_CREDENTIAL_SERVER_CERTIFICATE was renamed to more generic TLS_CREDENTIAL_PUBLIC_CERTIFICATE to better reflect the purpose of this credential type.

  • The MQTT public API function mqtt_disconnect() has changed. The function now accepts additional param parameter to support MQTT 5.0 case. The parameter is optional and not used with older MQTT versions - MQTT 3.1.1 users should pass NULL as an argument.

  • The AF_PACKET/SOCK_RAW/IPPROTO_RAW socket combination is no longer supported, as AF_PACKET sockets should only accept IEEE 802.3 protocol numbers. As an alternative, AF_PACKET/SOCK_DGRAM/ETH_P_ALL or AF_INET(6)/SOCK_RAW/IPPROTO_IP sockets can be used, depending on the actual use case.

  • The HTTP server now respects the configured _concurrent and _backlog values. Check that you provide applicable values to HTTP_SERVICE_DEFINE_EMPTY, HTTPS_SERVICE_DEFINE_EMPTY, HTTP_SERVICE_DEFINE and HTTPS_SERVICE_DEFINE.

  • CONFIG_NET_ZPERF no longer includes server support by default. To use the server commands, enable CONFIG_NET_ZPERF_SERVER. If server support is not needed, CONFIG_ZVFS_POLL_MAX can possibly be reduced.

  • The L2 Wi-Fi shell now supports interface option for most commands, to accommodate this change some of the existing options have been renamed. The following table summarizes the changes:

    Command(s)

    Old option

    New option

    wifi connect wifi ap enable

    -i

    -g

    wifi twt setup

    -i

    -p

    wifi ap config

    -i

    -t

    wifi mode wifi channel wifi packet_filter

    --if-index

    --iface

  • The http_response_cb_t HTTP client response callback signature has changed. The callback function now returns int instead of void. This allows the application to abort the HTTP connection. Existing applications need to update their response callback implementations. To retain current behavior, simply return 0 from the callback.

  • The API signature of net_mgmt event handler net_mgmt_event_handler_t and request handler net_mgmt_request_handler_t has changed. The management event type is changed from uint32_t to uint64_t. The change allows event number values to be bit masks instead of enum values. The layer code still stays as a enum value. The NET_MGMT_LAYER_CODE and NET_MGMT_GET_COMMAND can be used to get the layer code and management event command from the actual event value in the request or event handlers if needed.

  • The socket options for net_mgmt type sockets cannot directly be network management event types as those are now uint64_t and the socket option expects a normal 32 bit integer value. Because of this, a new SO_NET_MGMT_ETHERNET_SET_QAV_PARAM and SO_NET_MGMT_ETHERNET_GET_QAV_PARAM socket options are created that will replace the previously used NET_REQUEST_ETHERNET_GET_QAV_PARAM and NET_REQUEST_ETHERNET_GET_QAV_PARAM options.

OpenThread

  • The OpenThread stack integration in Zephyr has undergone a major refactor. The implementation has been moved from the Zephyr networking layer (subsys/net/l2/openthread/) to a dedicated module (modules/openthread/).

  • OpenThread is now a standalone module in Zephyr. It can be used independently of Zephyr’s networking stack (L2 and IEEE802.15.4 shim layers). This enables new use cases, such as applications that use OpenThread directly with their own IEEE802.15.4 driver, or that do not need the full Zephyr networking stack.

  • Most functions in the include/zephyr/net/openthread.h file have been deprecated. These deprecated APIs are still available for backward compatibility, but new applications should use the new APIs provided by the OpenThread module. The following list summarizes the changes:

    • Mutex handling:

      • Previously:

        • openthread_api_mutex_lock

        • openthread_api_mutex_try_lock

        • openthread_api_mutex_unlock

      • Now use:

        • openthread_mutex_lock()

        • openthread_mutex_try_lock()

        • openthread_mutex_unlock()

    • OpenThread starting:

      • Previously: openthread_start

      • Now use: openthread_run()

    • Callback registration:

      • Previously:

        • openthread_state_changed_cb_register

        • openthread_state_changed_cb_unregister

      • Now use:

        • openthread_state_changed_callback_register()

        • openthread_state_changed_callback_unregister()

    • Callback structure:

      • Previously: openthread_state_changed_cb

      • Now use: openthread_state_changed_callback

    • The following openthread_context struct fields are deprecated and shall not be used in new code anymore:

      • instance

      • api_lock

      • work_q

      • api_work

      • state_change_cbs

    • The new functions that were not present before:

      • openthread_init() to initialize the OpenThread stack.

      • openthread_stop() to stop and disable the OpenThread stack.

      • openthread_set_receive_cb() to set the receive callback for the OpenThread stack.

  • The OpenThread-related Kconfig options from subsys/net/l2/openthread/Kconfig have been moved to modules/openthread/Kconfig. All Kconfig options remain the same. You can still use them in the same way as before, but to modify them, use the new path in the menuconfig or guiconfig.

  • If the CONFIG_NET_L2_OPENTHREAD Kconfig option is enabled, Zephyr’s L2 layer will use the new OpenThread module API as its backend. The L2 layer no longer implements OpenThread itself, but delegates the implementation to the module.

  • For existing applications using OpenThread through Zephyr’s networking stack:

    • Your application should continue to work, as the old APIs are still available for compatibility. However, you are encouraged to migrate to the new APIs for future-proofing and use the new modular structure.

    • Update any references to OpenThread Kconfig options to use the new path (modules/openthread/Kconfig) in your configuration tools.

  • For applications using openthread_context or other deprecated APIs:

    • Begin migrating to the new APIs. The deprecated APIs will be removed in a future release.

    • Avoid direct use of openthread_context and related fields; use the new initialization and callback registration functions instead.

  • For new applications or those using OpenThread without Zephyr L2:

    • Use the new initialization (openthread_init()), run (openthread_run()), and callback registration APIs (openthread_state_change_callback_register()).

    • You can now use OpenThread directly, without enabling Zephyr’s L2 or IEEE802.15.4 layers, if your use case allows.

SPI

xSPI

  • On STM32 devices, external memories device tree descriptions for size and address are now split in two separate properties to comply with specification recommendations.

    For instance, following external flash description reg = <0x70000000 DT_SIZE_M(64)>; /* 512 Mbits / is changed to reg = <0>; size = <DT_SIZE_M(512)>; / 512 Mbits */.

    Note that the property gives the actual size of the memory device in bits. Previous mapping address information is now described in xspi node at SoC dtsi level.

Video

  • 8 bit RAW Bayer formats BGGR8 / GBRG8 / GRBG8 / RGGB8 have been renamed by adding a S prefix in front:

    VIDEO_PIX_FMT_BGGR8 becomes VIDEO_PIX_FMT_SBGGR8 VIDEO_PIX_FMT_GBRG8 becomes VIDEO_PIX_FMT_SGBRG8 VIDEO_PIX_FMT_GRBG8 becomes VIDEO_PIX_FMT_SGRBG8 VIDEO_PIX_FMT_RGGB8 becomes VIDEO_PIX_FMT_SRGGB8

  • On STM32 devices, the DCMI driver (st,stm32-dcmi) now relies on endpoint based video-interfaces.yaml bindings for sensor interface properties (such as bus width and synchronization signals). Also the capture-rate property has been replaced by the usage of the frame interval API video_set_frmival(). See (GitHub #89627).

  • video_endpoint_id enum has been dropped. It is no longer a parameter in any video API.

  • video_buf_type enum has been added. It is a required parameter in the following video APIs:

    set_stream video_stream_start video_stream_stop

Audio

  • The binding file for cirrus,cs43l22 has been renamed to have a name matching the compatible string.

Other subsystems

hawkBit

State Machine Framework

  • smf_set_handled() has been removed.

  • State run actions now return an smf_state_result value instead of void. and the return code determines if the event is propagated to parent run actions or has been handled. A run action that handles the event completely should return SMF_EVENT_HANDLED, and run actions that propagate handling to parent states should return SMF_EVENT_PROPAGATE.

  • Flat state machines ignore the return value; returning SMF_EVENT_HANDLED would be the most technically accurate response.

Modules

CMSIS

  • Cortex-M boards/socs now require the CMSIS_6 module to build properly (instead of cmsis which was CMSIS 5.9.0). If trying to build a Cortex-M board, do a west update to make sure that CMSIS_6 module is available before running west build or other commands.

    Boards or SOCs or modules using the older cmsis module either with a local copy or via the CONFIG_ZEPHYR_CMSIS_MODULE_DIR are requested to move to the CMSIS_6 module which can be accessed via the CONFIG_ZEPHYR_CMSIS_6_MODULE_DIR configuration.

    Note: Zephyr will continue using the older cmsis module for Cortex-A and Cortex-R targets.

Architectures