Book a Technical Call
Book a Technical Call

Home › SDK migration

SDK upgrade guide

Zephyr 3.7 to Zephyr 4.2: what needs attention

Migratorisk's knowledge base lists 64 documented changes between Zephyr 3.7 and Zephyr 4.2 across 3 releases. 61 of them are rated likely to break code, configuration or builds that use them. Below is each change, what a scan also reviews on this path, and how to see which ones apply to your project.

64documented changes
61rated will or likely to break
10review checks on this path

Find which of these affect your firmware

Migratorisk scans your project on your own computer and reports only the changes your code, configuration and build actually touch. Your source code is not uploaded.

python -m pip install migratorisk
migratorisk scan --project ./your-firmware --from zephyr-3.7.0 --to zephyr-4.2.0 --out report.html

Requires Python 3.12 or newer. Results are free and complete without sign-up; sharing a report with us is optional.

Set up the local scanOr answer a few questions instead

Where the changes are

Hardware description · 22Build settings · 21Application code · 21

What changes between Zephyr 3.7 and Zephyr 4.2

Ordered by impact. Each item names the release that introduced it and links to the official source. A change only matters if your project uses what changed; the scan checks that.

Likely to break

Devicetree compatibles renesas,ra-gpio and 4 more were removed

Hardware description · Zephyr 4.2.0 · Source

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. Covers 5 names.

Likely to break

Kconfig options CONFIG_REGULATOR_NPM1300 and 2 more were renamed

Build settings · Zephyr 4.2.0 · Source

Renamed CONFIG_REGULATOR_NPM1300 to CONFIG_REGULATOR_NPM13XX, CONFIG_REGULATOR_NPM1300_COMMON_INIT_PRIORITY to REGULATOR_NPM13XX_COMMON_INIT_PRIORITY, CONFIG_REGULATOR_NPM1300_INIT_PRIORITY to CONFIG_REGULATOR_NPM13XX_INIT_PRIORITY. Covers 3 names.

Likely to break

APIs LINK_FULL_5000BASE_T and 1 more were renamed

Application code · Zephyr 4.2.0 · Source

Enums for the Ethernet speed have been renamed to be more independent of the used medium. Covers 2 names.

Likely to break

Devicetree compatibles microchip,mcp230xx and 1 more were removed

Hardware description · Zephyr 4.0.0 · Source

The devicetree bindings for the Microchip mcp23xxx series have been split up. Users of microchip,mcp230xx and microchip,mcp23sxx should change their devicetree compatible values to the specific chip variant, e.g. microchip,mcp23017. The ngpios devicetree property has been removed, since it is implied by the model name. Covers 2 names.

Likely to break

Kconfig options CONFIG_DISABLE_SSBD and 1 more were removed

Build settings · Zephyr 4.1.0 · Source

Kconfigs CONFIG_DISABLE_SSBD and CONFIG_ENABLE_EXTENDED_IBRS have been deprecated since v3.7. These were removed. Use CONFIG_X86_DISABLE_SSBD and CONFIG_X86_ENABLE_EXTENDED_IBRS instead. Covers 2 names.

Likely to break

Kconfig options CONFIG_GPIO_NPM1300 and 1 more were renamed

Build settings · Zephyr 4.2.0 · Source

Renamed CONFIG_GPIO_NPM1300 to CONFIG_GPIO_NPM13XX, CONFIG_GPIO_NPM1300_INIT_PRIORITY to CONFIG_GPIO_NPM13XX_INIT_PRIORITY. Covers 2 names.

Likely to break

Kconfig options CONFIG_MBEDTLS_TLS_VERSION_1_0 and 1 more were removed

Build settings · Zephyr 4.0.0 · Source

The Kconfig options CONFIG_MBEDTLS_TLS_VERSION_1_0 and CONFIG_MBEDTLS_TLS_VERSION_1_1 have been removed because Mbed TLS doesn't support TLS 1.0 and 1.1 anymore since v3.0. Covers 2 names.

Likely to break

Kconfig options CONFIG_MFD_NPM1300 and 1 more were renamed

Build settings · Zephyr 4.2.0 · Source

Renamed CONFIG_MFD_NPM1300 to CONFIG_MFD_NPM13XX, CONFIG_MFD_NPM1300_INIT_PRIORITY to CONFIG_MFD_NPM13XX_INIT_PRIORITY. Covers 2 names.

Likely to break

Kconfig options CONFIG_WDT_NPM1300 and 1 more were renamed

Build settings · Zephyr 4.2.0 · Source

Renamed CONFIG_WDT_NPM1300 to CONFIG_WDT_NPM13XX, CONFIG_WDT_NPM1300_INIT_PRIORITY to CONFIG_WDT_NPM13XX_INIT_PRIORITY. Covers 2 names.

Likely to break

Kconfig options SB_CONFIG_MCUBOOT_MODE_SWAP_WITHOUT_SCRATCH and 1 more were replaced

Build settings · Zephyr 4.1.0 · Source

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. Covers 2 names.

Likely to break

API BT_AUDIO_BROADCAST_CODE_SIZE was removed

Application code · Zephyr 4.0.0 · Source

BT_AUDIO_BROADCAST_CODE_SIZE has been removed and BT_ISO_BROADCAST_CODE_SIZE should be used instead.

Likely to break

API BT_AUDIO_CONTEXT_TYPE_PROHIBITED was renamed

Application code · Zephyr 4.2.0 · Source

BT_AUDIO_CONTEXT_TYPE_PROHIBITED has been renamed to BT_AUDIO_CONTEXT_TYPE_NONE.

Likely to break

API ETH_STM32_MODE_HALFDUPLEX was removed

Application code · Zephyr 4.2.0 · Source

The Kconfig options ETH_STM32_HAL_PHY_ADDRESS, ETH_STM32_CARRIER_CHECK, ETH_STM32_CARRIER_CHECK_RX_IDLE_TIMEOUT_MS, ETH_STM32_AUTO_NEGOTIATION_ENABLE, ETH_STM32_SPEED_10M, ETH_STM32_MODE_HALFDUPLEX have been removed, as they are no longer needed, and the driver now uses the ethernet phy api to communicate with the phy driver, which is responsible for configuring the phy settings.

Likely to break

API MGMT_CB_ERROR_RET was removed

Application code · Zephyr 4.1.0 · Source

The deprecated macro MGMT_CB_ERROR_RET has been removed.

Likely to break

API NET_REQUEST_ETHERNET_SET_AUTO_NEGOTIATION was removed

Application code · Zephyr 4.2.0 · Source

ETHERNET_CONFIG_TYPE_LINK, ETHERNET_CONFIG_TYPE_DUPLEX, ETHERNET_CONFIG_TYPE_AUTO_NEG and the related NET_REQUEST_ETHERNET_SET_LINK, NET_REQUEST_ETHERNET_SET_DUPLEX, NET_REQUEST_ETHERNET_SET_AUTO_NEGOTIATION have been removed. phy_configure_link together with net_eth_get_phy should be used instead to configure the link.

Likely to break

API NET_SOCKET_SERVICE_SYNC_DEFINE_STATIC was removed

Application code · Zephyr 4.0.0 · Source

The work_q parameter to NET_SOCKET_SERVICE_SYNC_DEFINE and NET_SOCKET_SERVICE_SYNC_DEFINE_STATIC has been removed as it was always ignored.

Likely to break

API PIXEL_FORMAT_RGB565 was replaced

Application code · Zephyr 4.2.0 · Source

On STM32 devices, the LTDC driver (st,stm32-ltdc) RGB565 format PIXEL_FORMAT_RGB565 has been replaced by PIXEL_FORMAT_BGR565 to match the format expected by Zephyr. This change ensures proper behavior of both display and video capture samples.

Likely to break

API TLS_CREDENTIAL_SERVER_CERTIFICATE was renamed

Application code · Zephyr 4.2.0 · Source

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.

Likely to break

API bt_csip_set_member_get_sirk was removed

Application code · Zephyr 4.2.0 · Source

bt_csip_set_member_get_sirk has been removed. Use bt_csip_set_member_get_info to get the SIRK (and other information).

Likely to break

API counter_native_posix was renamed

Application code · Zephyr 4.2.0 · Source

counter_native_posix has been renamed counter_native_sim, and with it its kconfig options and DT binding. zephyr,native-posix-counter has been deprecated in favor of zephyr,native-sim-counter. And CONFIG_COUNTER_NATIVE_POSIX and its related options with CONFIG_COUNTER_NATIVE_SIM.

Likely to break

API ethernet_native_posix was renamed

Application code · Zephyr 4.2.0 · Source

ethernet_native_posix has been renamed ethernet_native_tap, and with it its kconfig options: CONFIG_ETH_NATIVE_POSIX and its related options have been deprecated in favor of CONFIG_ETH_NATIVE_TAP.

Likely to break

API fake_entropy_native_posix was renamed

Application code · Zephyr 4.2.0 · Source

fake_entropy_native_posix has been renamed fake_entropy_native_sim, and with it its kconfig options and DT binding. zephyr,native-posix-rng has been deprecated in favor of zephyr,native-sim-rng. And CONFIG_FAKE_ENTROPY_NATIVE_POSIX and its related options with CONFIG_FAKE_ENTROPY_NATIVE_SIM.

Likely to break

API native_posix_timer was renamed

Application code · Zephyr 4.2.0 · Source

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

Likely to break

API net_linkaddr_storage was renamed

Application code · Zephyr 4.2.0 · Source

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.

Likely to break

API stepper_enable_constant_velocity_mode was renamed

Application code · Zephyr 4.1.0 · Source

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.

Likely to break

API stepper_set_actual_position was renamed

Application code · Zephyr 4.1.0 · Source

Renamed the stepper_set_actual_position function to stepper_set_reference_position.

Likely to break

API stepper_set_max_velocity was renamed

Application code · Zephyr 4.1.0 · Source

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.

Likely to break

API stepper_set_target_position was renamed

Application code · Zephyr 4.1.0 · Source

Renamed the stepper_set_target_position function to stepper_move_to.

Likely to break

API uart_native_posix was renamed

Application code · Zephyr 4.2.0 · Source

uart_native_posix has been renamed uart_native_pty, and with it its kconfig options and DT binding. zephyr,native-posix-uart has been deprecated in favor of zephyr,native-pty-uart. CONFIG_UART_NATIVE_POSIX and its related options with CONFIG_UART_NATIVE_PTY.

Likely to break

CONFIG_BT_CTLR deprecated in favour of HAS_BT_CTLR

Build settings · Zephyr 4.1.0 · Source

Zephyr 4.1 deprecates CONFIG_BT_CTLR; the link layer is now chosen by HCI driver options that select HAS_BT_CTLR. Setting CONFIG_BT_CTLR in prj.conf or a sysbuild image config fails on later releases.

Likely to break

Devicetree compatible litex,eth0 was renamed

Hardware description · Zephyr 4.0.0 · Source

The compatible of the LiteX ethernet controller has been renamed from litex,eth0 to litex,liteeth.

Likely to break

Devicetree compatible litex,uart0 was renamed

Hardware description · Zephyr 4.0.0 · Source

The compatible of the LiteX uart controller has been renamed from litex,uart0 to litex,uart.

Likely to break

Devicetree compatible microchip,mcp9808 was renamed

Hardware description · Zephyr 4.0.0 · Source

The existing driver for the Microchip MCP9808 temperature sensor transformed and renamed to support all JEDEC JC 42.4 compatible temperature sensors. It now uses the jedec,jc-42.4-temp compatible string instead to the microchip,mcp9808 string.

Likely to break

Devicetree compatible nxp,imx-lpi2c was renamed

Hardware description · Zephyr 4.1.0 · Source

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

Likely to break

Devicetree compatible nxp,imx-lpspi was renamed

Hardware description · Zephyr 4.1.0 · Source

Renamed the compatible from nxp,imx-lpspi to nxp,lpspi.

Likely to break

Devicetree compatible nxp,kinetis-adc12 was renamed

Hardware description · Zephyr 4.1.0 · Source

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

Likely to break

Devicetree compatible nxp,kinetis-dspi was renamed

Hardware description · Zephyr 4.1.0 · Source

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

Likely to break

Devicetree compatible nxp,kinetis-ftm was renamed

Hardware description · Zephyr 4.1.0 · Source

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

Likely to break

Devicetree compatible nxp,kinetis-ftm-pwm was renamed

Hardware description · Zephyr 4.1.0 · Source

Renamed the compatible from nxp,kinetis-ftm-pwm to nxp,ftm-pwm.

Likely to break

Devicetree compatible nxp,kinetis-lpuart was renamed

Hardware description · Zephyr 4.1.0 · Source

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

Likely to break

Devicetree compatible nxp,kinetis-mpu was renamed

Hardware description · Zephyr 4.1.0 · Source

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

Likely to break

Devicetree compatible nxp,kinetis-pinctrl was renamed

Hardware description · Zephyr 4.1.0 · Source

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

Likely to break

Devicetree compatible nxp,kinetis-pinmux was renamed

Hardware description · Zephyr 4.1.0 · Source

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

Likely to break

Devicetree compatible nxp,kinetis-rtc was renamed

Hardware description · Zephyr 4.1.0 · Source

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

Likely to break

Devicetree compatible nxp,kinetis-wdog32 was renamed

Hardware description · Zephyr 4.1.0 · Source

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

Likely to break

Devicetree compatible renesas,ra8-pwm was renamed

Hardware description · Zephyr 4.1.0 · Source

Renamed the compatible from renesas,ra8-pwm to renesas,ra-pwm.

Likely to break

Devicetree compatible silabs,gecko-spi-eusart was renamed

Hardware description · Zephyr 4.1.0 · Source

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

Likely to break

Devicetree compatible silabs,gecko-spi-usart was renamed

Hardware description · Zephyr 4.1.0 · Source

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

Likely to break

Devicetree compatible ti,ads114s0x-gpio was renamed

Hardware description · Zephyr 4.1.0 · Source

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

Likely to break

Devicetree compatible zephyr,gpio-steppers was renamed

Hardware description · Zephyr 4.1.0 · Source

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

Likely to break

Kconfig option CONFIG_BT_CSIP_SET_MEMBER_NOTIFIABLE was renamed

Build settings · Zephyr 4.2.0 · Source

CONFIG_BT_CSIP_SET_MEMBER_NOTIFIABLE has been renamed to CONFIG_BT_CSIP_SET_MEMBER_SIRK_NOTIFIABLE.

Likely to break

Kconfig option CONFIG_BT_ISO_TX_FRAG_COUNT was removed

Build settings · Zephyr 4.2.0 · Source

The CONFIG_BT_ISO_TX_FRAG_COUNT Kconfig option was removed as it was completely unused. Any uses of it can simply be removed.

Likely to break

Kconfig option CONFIG_LED_NPM1300 was renamed

Build settings · Zephyr 4.2.0 · Source

Renamed CONFIG_LED_NPM1300 to CONFIG_LED_NPM13XX.

Likely to break

Kconfig option CONFIG_MAX_FILES was renamed

Build settings · Zephyr 4.1.0 · Source

The EXT2 Kconfig symbol CONFIG_MAX_FILES has been renamed to CONFIG_EXT2_MAX_FILES.

Likely to break

Kconfig option CONFIG_MBEDTLS_SSL_EXPORT_KEYS was removed

Build settings · Zephyr 4.0.0 · Source

The Kconfig option CONFIG_MBEDTLS_SSL_EXPORT_KEYS was removed because the corresponding build symbol was removed in Mbed TLS 3.1.0 and is now assumed to be enabled.

Likely to break

Kconfig option CONFIG_MCUBOOT_CMAKE_WEST_SIGN_PARAMS was removed

Build settings · Zephyr 4.0.0 · Source

Removed the CONFIG_MCUBOOT_CMAKE_WEST_SIGN_PARAMS Kconfig option as west sign is no longer called by the build system when signing images for MCUboot.

Likely to break

Kconfig option CONFIG_NPM1300_CHARGER was renamed

Build settings · Zephyr 4.2.0 · Source

Renamed CONFIG_NPM1300_CHARGER to CONFIG_NPM13XX_CHARGER.

Likely to break

Kconfig option CONFIG_SOC_SERIES_RP2XXX was renamed

Build settings · Zephyr 4.1.0 · Source

CONFIG_SOC_SERIES_RP2XXX is renamed to CONFIG_SOC_SERIES_RP2040.

Likely to break

Kconfig option CONFIG_SPI_MCUX_LPSPI was renamed

Build settings · Zephyr 4.2.0 · Source

Renamed CONFIG_SPI_MCUX_LPSPI to CONFIG_SPI_NXP_LPSPI, and similar for any child configs for that driver, including CONFIG_SPI_NXP_LPSPI_DMA and CONFIG_SPI_NXP_LPSPI_CPU.

Likely to break

Kconfig option CONFIG_SPI_NOR_IDLE_IN_DPD was removed

Build settings · Zephyr 4.0.0 · Source

CONFIG_SPI_NOR_IDLE_IN_DPD has been removed from the CONFIG_SPI_NOR driver. An enhanced version of this functionality can be obtained by enabling pm-device-runtime on the device (Tunable with CONFIG_SPI_NOR_ACTIVE_DWELL_MS).

And 4 more changes, all checked by the scan.

What a scan of this path also reviews

Beyond the documented changes, Migratorisk reviews these upgrade risks for Zephyr projects on this path. Each one is reported only when the project shows the trigger.

Devicetree binding error found in Zephyr migration build log

When it applies: Build log reports a devicetree binding error.

Why it matters: Devicetree bindings and board model assumptions can change across Zephyr major versions.

What to do: Fix devicetree binding errors before treating source API findings as migration failures.

Undefined Kconfig symbol found in Zephyr migration build log

When it applies: Build log reports an undefined Kconfig symbol.

Why it matters: Zephyr major-version upgrades can remove, rename, or change dependencies for Kconfig symbols.

What to do: Resolve undefined Kconfig symbols before chasing later source or linker errors.

Custom board needs Zephyr 4.x devicetree and Kconfig review

When it applies: The project contains a custom board definition.

Why it matters: Board files track SoC devicetree, pinctrl, Kconfig and hardware model changes between releases.

What to do: Compare the custom board with a similar in-tree board in the target release (board.yml, chosen nodes, pinctrl, partitions, SoC Kconfig).

Hardcoded Zephyr path found

When it applies: CMake contains a hardcoded Zephyr or SDK path.

Why it matters: Hardcoded workspace paths often break when moving to a new Zephyr major-version workspace.

What to do: Replace hardcoded paths with west/CMake discovery mechanisms.

Verify OTA from the current field firmware

When it applies: The project uses MCUboot, so devices in the field keep their current bootloader after the upgrade.

Why it matters: The upgraded image must still be accepted by the existing bootloader (signature type, key, slot layout and image header).

What to do: Keep the signing key, signature type and slot layout unchanged, and test an OTA update from the current production image on hardware.

Missing header found in Zephyr migration build log

When it applies: Build log reports a missing header.

Why it matters: Missing headers can indicate moved APIs, missing modules, or include path changes after a major-version upgrade.

What to do: Identify whether the header moved, the module is missing, or the API was removed.

Undefined reference found in Zephyr migration build log

When it applies: Build log reports an undefined reference.

Why it matters: Link failures can be caused by missing modules, changed Kconfig dependencies, or removed APIs.

What to do: Resolve earlier Kconfig and devicetree errors first, then review the missing symbol owner.

West manifest references old Zephyr revision

When it applies: west.yml references an old Zephyr or NCS revision.

Why it matters: Manifest revisions control module versions and can block a clean major-version migration.

What to do: Update manifest revisions intentionally before debugging project-local failures.

Source API review pattern found

When it applies: Source uses APIs that deserve review during a Zephyr 4.x migration.

Why it matters: This evidence is review-only unless the upgraded build log confirms a concrete missing symbol or header.

What to do: Review source API usage after west, Kconfig, and devicetree issues are addressed.

First Zephyr build-log migration error found

When it applies: Build log contains a first high-signal error for migration triage.

Why it matters: Early build errors often cause later cascading noise.

What to do: Fix this first error before treating later build-log lines as independent migration work.

VelocityCreate

Want us to handle the upgrade?

VelocityCreate can review your assessment, agree on the migration scope, and carry out the firmware changes and agreed verification. Discuss your deadline, hardware, and requirements with an embedded engineer.

Discuss my migrationBook a technical call

The initial discussion is free. Implementation is quoted separately.

Related upgrade paths

Generated from the rule catalog of Migratorisk 0.3.0. This is an automated summary of published SDK changes, not a review of your project, and it does not replace builds and device tests. How the scanner is validated.

Menu