Migration guide to Zephyr v4.5.0 (Working Draft)

This document describes the changes required when migrating your application from Zephyr v4.4.0 to Zephyr v4.5.0.

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

Common

Build System

Kernel

  • _k_neg_eagain has been renamed to _errno_neg_egain as errno has been migrated out of kernel into lib/libc/common.

Boards

  • The Kconfig options CONFIG_SRAM_SIZE and CONFIG_SRAM_BASE_ADDRESS have been deprecated, boards should instead use the devicetree zephyr.sram chosen node to specify the RAM node which will be used (whose values populated the Kconfig values). If either option is manually adjusted, it will cause CONFIG_SRAM_DEPRECATED_KCONFIG_SET to be set which indicates this deprecation.

  • The internal Nordic SoC platform Kconfig symbols NRF_PLATFORM_HALTIUM and NRF_PLATFORM_LUMOS are no longer used by in-tree code, which now relies on explicit CONFIG_SOC_SERIES_NRF54H, CONFIG_SOC_SERIES_NRF92, CONFIG_SOC_SERIES_NRF54L and CONFIG_SOC_SERIES_NRF71 checks. Both symbols are kept as deprecated stubs that default to y when the corresponding SoC series is selected, so existing CONFIG_NRF_PLATFORM_*=y lines and depends on NRF_PLATFORM_* clauses keep building with a Kconfig deprecation warning. Out-of-tree Kconfig, CMake and code using these symbols should be updated:

  • The Nordic sysbuild Kconfig option SB_CONFIG_NRF_HALTIUM_GENERATE_UICR has been renamed to SB_CONFIG_NRF_GENERATE_UICR. Update sysbuild configurations to use the new name.

  • The Nordic SoC headers <haltium_power.h> and <haltium_pm_s2ram.h> have been renamed to <soc_power.h> and <soc_pm_s2ram.h> respectively. Forwarder headers under the old names remain available and emit a #warning pointing to the new include paths. Out-of-tree code that includes the old paths should be updated:

    • #include <haltium_power.h> with #include <soc_power.h>.

    • #include <haltium_pm_s2ram.h> with #include <soc_pm_s2ram.h>.

  • The system clock on STM32H7RS-based boards (stm32h7s78_dk and nucleo_h7s3l8) has been increased to 600 MHz. This is achieved by increasing the PLL1 frequency to 300 MHz, which also affects the bus and kernel clocks, resulting in slightly higher frequencies.

Device Drivers and Devicetree

Haptics

  • The DEVICE_API macro is now mandatory for declaring device driver API instances of any upstream driver class, including in out-of-tree drivers. DEVICE_API_GET now asserts that the API belongs to the requested class, which requires the instance to live in the class’s iterable section. Out-of-tree driver classes that embed an upstream API as their first member must also declare the relationship with DEVICE_API_EXTENDS, so that DEVICE_API_GET for the parent class succeeds on devices implementing the child API. See Driver APIs for details.

ADC

  • The girqs and pcrs properties (array type) of microchip,xec-adc have been replaced by encoded girqs (using MCHP_XEC_ECIA_GIRQ_ENC macros) and pcr-scr (int type) for encoded PCR register index and bit position (GitHub #105658).

Clock Control

  • The nxp,imxrt11xx-arm-pll binding now uses loop-div and post-div for ARM PLL configuration. The legacy clock-mult and clock-div properties remain supported but are deprecated. Existing RT11xx overlays should be updated using the mapping loop-div = clock-mult * 2 and post-div = clock-div.

Devicetree

  • int and array typed devicetree properties whose DTS source uses a negative literal (e.g. <(-1)>) now expand to a negative value instead of the two’s-complement unsigned value used previously. Code that relied on the old unsigned representation, for example unsigned comparisons or BUILD_ASSERT(DT_PROP(node, foo) > 0, ...) checks, must be updated to use signed types or signed-aware checks (GitHub #107271).

Digital Microphone

  • The DMIC driver backend API now uses dmic_driver_api instead of struct _dmic_ops.

    Out-of-tree DMIC drivers must rename their backend API struct definitions and switch their API instances to DEVICE_API(dmic, ...). See GitHub #107695 for examples of how in-tree drivers have been updated. Application code using dmic_configure(), dmic_trigger(), and dmic_read() is not impacted.

Display

  • The Kconfig options CONFIG_SDL_DISPLAY_DEFAULT_PIXEL_FORMAT_* for SDL display pixel-format selection have been removed in favour of setting the pixel-format property directly in devicetree on the SDL pseudo-device node using the PANEL_PIXEL_FORMAT_* macros from include/zephyr/dt-bindings/display/panel.h. (GitHub #104099)

Ethernet

Flash

  • jedec,spi-nand now requires a plane-bytes property, which indicates the size of each plane in the flash device. For devices with a single plane, this should be set to the same value as size-bytes.

GPIO

  • The STM32 GPIO driver now returns -EINVAL when attempting to configure a GPIO pin in disabled state with a pull-up/pull-down resistor using gpio_pin_configure(). The driver would previously return 0 without actually honoring those flags (no PU/PD resistor was enabled). Applications encountering this error should remove GPIO_PULL_UP/ GPIO_PULL_DOWN from the flags they provide to gpio_pin_configure(); this will result in the same behavior as before since these flags were effectively ignored. (GitHub #104690)

  • On STM32F1 series, GPIO output pins now use 50 MHz max. speed instead of 10 MHz. (GitHub #104690)

Input

  • The no-disconnect property of gpio-keys has been replaced by enumeration property zephyr,suspend-action. The new property currently has three values, two of which are direct replacements for the old situations:

    • zephyr,suspend-action = "none"; is the remplacement for the behavior when when no-disconnect was present. Users of the no-disconnect property should replace it with zephyr,suspend-action = "none";.

    • zephyr,suspend-action = "disconnect-with-pupd"; is the replacement for the behavior when no-disconnect was not present. This is selected by default for backwards compatibility with the previous behavior.

    • zephyr,suspend-action = "full-disconnect"; is a new value. (Refer to the binding for more details)

    Users of the default configuration are advised to reconsider whether it really is appropriate; migration to zephyr,suspend-action = "full-disconnect"; is recommended. (GitHub #108294)

  • Kconfig options for the ft6146, ft5336, and cst8xx input drivers have been renamed to be consistent with the other input drivers. Applications using the following Kconfig options must update their configurations accordingly:

NXP

  • CONFIG_MCUX_LPTMR_TIMER no longer defaults to y based on the /chosen/zephyr,system-timer chosen node being compatible with nxp,lptmr. Out-of-tree SoCs and boards that rely on the LPTMR as the system timer must now explicitly default the symbol in their Kconfig.defconfig (for example default y if PM).

  • Kinetis KE1xF no longer requires a board overlay to designate the system timer when CONFIG_PM is enabled. The SoC DTSI now sets the zephyr,system-timer chosen property, so boards that added the overlay described in the Zephyr 4.4 migration guide can remove it.

PWM

  • The pcrs property (array type) of microchip,xec-pwm has been replaced by pcr-scr (int type) to use encoded PCR register index and bit position macros (GitHub #104570).

  • STM32 PWM DT bindings macro PWM_STM32_COMPLEMENTARY that is deprecated since Zephyr v3.3.0 is no more defined. One shall use STM32_PWM_COMPLEMENTARY instead.

SD Host Controller

  • Renamed the Kconfig option CONFIG_SDHC_STM32_POLLING_SUPPORT to CONFIG_SDHC_STM32_DMA_MODE. The new symbol enables DMA (default y); set it to n to use polling mode. (GitHub #101617)

  • Renamed the Kconfig option CONFIG_SDHC_STM32_SDIO to CONFIG_SDHC_STM32_SDMMC. (GitHub #101617)

  • The devicetree compatible st,stm32-sdio was renamed. Use st,stm32-sdmmc instead. With this compatible, the legacy disk driver and the SDHC driver can target the same node. To migrate to the SDHC STM32 SDMMC driver, disable the legacy disk driver:

    CONFIG_SDMMC_STM32=n

    (GitHub #101617)

  • For st,stm32-sdmmc, the sdhi-on-gpios property has been consolidated into the existing pwr-gpios property. Replace sdhi-on-gpios with pwr-gpios in out-of-tree devicetree nodes.

  • litex,mmc now uses the dma-coherent devicetree property to indicate that the controller’s DMA accesses are coherent with the CPU. CONFIG_SDHC_LITEX_LITESDCARD_NO_COHERENT_DMA is automatically set based on that property and is no longer user-configurable. (GitHub #108411)

Sensor

  • The girqs and pcrs properties (array type) of microchip,xec-tach have been replaced by pcr-scr (int type) to use encoded PCR register index and bit position macros. GIRQ configuration is now handled via the microchip,dmec-ecia-girq binding include (GitHub #104808).

Serial

STM32

  • gpio-keys devices will fail to suspend unless property zephyr,suspend-action is present in Devicetree with value "none" or "full-disconnect". Refer to the migration guide entry related to this binding for more details. (GitHub #104690 / GitHub #108294)

  • SoC DTSI files now consistently use interrupt priority zero for all peripherals. Applications must now explicitly configure interrupt priorities using Devicetree if they previously relied on the values found in SoC DTSI files. (GitHub #106188)

Syscon

  • The syscon API functions syscon_read_reg() and syscon_write_reg() now use uint32_t for the register offset parameter instead of uint16_t. This allows for larger register offsets. Code that explicitly declares uint16_t variables for the register parameter or implements the syscon driver API functions may need to be updated.

USB

  • On STM32N6, the clocks cell which configures the USBPHYC clock mux has been moved from usbotg_hsN to usbphycN nodes at SoC DTSI level. Boards which use an STM32N6 SoC with custom clock mux configuration must now set the clocks property on usbphycN instead of usbotg_hsN. (GitHub #107813)

WiFi

  • In the functions implemented by the net_wifi_mgmt_offload, internally ethernet_api and wifi_mgmt_ops, a additional argument was added for a pointer to net_if. This api is not directly exposed to the application, so only out-of-tree drivers need to be updated. (GitHub #106086)

  • The Espressif Wi-Fi driver Kconfig option CONFIG_ESP32_WIFI_STA_AUTO_DHCPV4 has been removed in favor of the generic CONFIG_WIFI_STA_AUTO_DHCPV4. Applications that previously disabled the Espressif-specific option must now disable the generic option to retain manual DHCPv4 or static IP behavior after STA connection.

Bluetooth

Bluetooth Audio

Bluetooth Classic

  • The BR/EDR specific callbacks role_changed and br_mode_changed in bt_conn_cb have been moved into a new sub-struct bt_conn_br_cb, accessible via the br member. Application code using these callbacks must update the designated initializers:

    • .role_changed → .br.role_changed

    • .br_mode_changed → .br.mode_changed

    (GitHub #108022)

Bluetooth HCI

  • The devicetree compatible bflb,bl70x-bt-hci has been renamed to bflb,bt-hci, now that a single binding covers all Bouffalo Lab on-chip BLE controllers (BL60x/BL70x/BL70XL). Out-of-tree boards and shields must update their devicetree nodes accordingly.

Networking

  • Various IP routing related Kconfig options will have now IPV6 prefix added to them. This is done so that we can have IPv4 routing symbols that provide same functionality as IPv6 ones but can be controlled separately.

  • IPv4 and IPv6 unicast route-table support is now exposed through the CONFIG_NET_IPV4_ROUTE and CONFIG_NET_IPV6_ROUTE options.

    These options control the per-family unicast route tables that are used by static route management, networking shell route commands, and host-side route selection for locally originated traffic such as VPN-bound packets. They do not, by themselves, enable packet forwarding between interfaces.

  • The Kconfig options CONFIG_NET_IPV4_ROUTING and CONFIG_NET_IPV6_ROUTING have been renamed to CONFIG_NET_IPV4_FORWARDING and CONFIG_NET_IPV6_FORWARDING.

    The renamed options explicitly describe IP forwarding between interfaces. Applications that only need route-table lookups or static routes should enable CONFIG_NET_IPV4_ROUTE or CONFIG_NET_IPV6_ROUTE and leave forwarding disabled. Applications acting as routers should enable both the route-table option and the corresponding forwarding option.

  • Out-of-tree IPv6 configurations should also migrate away from the deprecated legacy aliases CONFIG_NET_ROUTE, CONFIG_NET_ROUTING, CONFIG_NET_MAX_ROUTES, and CONFIG_NET_MAX_NEXTHOPS and use the CONFIG_NET_IPV6_* symbols directly.

Ethernet

PTP

gPTP

  • Converted int port to uint16_t gptp_port in ethernet_context to make it clear that the field used only by the gPTP stack to store the gPTP port number.

  • Used uint16_t for nb_ports in gptp_default_ds per IEEE 1588 standard.

  • Removed net_eth_get_ptp_port and net_eth_set_ptp_port. New gptp_get_port_number() and gptp_set_port_number() can be used instead.

LoRaWAN

Other subsystems

  • Demand paging (subsys/demand_paging) is moved under Memory Management into subsys/mem_mgmt/demand_paging. Custom backing store and eviction algorithm code need to be moved there.

  • The ring buffer “item” API in <zephyr/sys/ring_buffer.h> has been deprecated in favor of the new fixed-size queue API in <zephyr/sys/ringq.h>.

    Code storing fixed-size items should migrate to sys_ringq (see sys_ringq Data Structure). Code that only used the item API at the byte level should switch to the byte-mode functions ring_buf_put() / ring_buf_get() calls on the same ring_buf. (GitHub #98255)

  • The ZTEST_BENCHMARK_SETUP_TEARDOWN() and ZTEST_BENCHMARK_TIMED_SETUP_TEARDOWN() macros have been removed. Their setup/teardown signature has been folded into ZTEST_BENCHMARK() and ZTEST_BENCHMARK_TIMED(), which now require explicit setup_fn and teardown_fn arguments at every call site. Pass NULL when a benchmark genuinely needs neither.

    Update existing call sites as follows:

    /* Before */
ZTEST_BENCHMARK(suite, my_bench, 100) { /* ... */ }
ZTEST_BENCHMARK_TIMED(suite, my_bench, 1000) { /* ... */ }
ZTEST_BENCHMARK_SETUP_TEARDOWN(suite, my_bench, 100, setup, teardown) { /* ... */ }
ZTEST_BENCHMARK_TIMED_SETUP_TEARDOWN(suite, my_bench, 1000, setup, teardown) { /* ... */ }

/* After */
ZTEST_BENCHMARK(suite, my_bench, 100, NULL, NULL) { /* ... */ }
ZTEST_BENCHMARK_TIMED(suite, my_bench, 1000, NULL, NULL) { /* ... */ }
ZTEST_BENCHMARK(suite, my_bench, 100, setup, teardown) { /* ... */ }
ZTEST_BENCHMARK_TIMED(suite, my_bench, 1000, setup, teardown) { /* ... */ }

Modules

hal_nxp

  • S32K344: The pinmux header file for this SoC was renamed from S32K344-172MQFP-pinctrl.h to S32K344_K324_K314_172HDQFP-pinctrl.h. Out-of-tree boards must update their include directive accordingly:

    #include <nxp/s32/S32K344_K324_K314_172HDQFP-pinctrl.h>

Mbed TLS

Architectures

  • A new architecture primitive, arch_cpu_irqs_are_enabled(), has been added. It returns the current interrupt-enable state of the calling CPU without modifying it, complementing arch_irq_unlocked() which inspects a saved key. Out-of-tree architecture ports must provide an implementation.