Migration guide to Zephyr v4.4.0 (Working Draft)

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

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

Build System

  • Zephyr now officially defaults to C17 (ISO/IEC 9899:2018) as its minimum required C standard version. If your toolchain does not support this standard you will need to use one of the existing and now deprecated options: CONFIG_STD_C99 or CONFIG_STD_C11.

Kernel

Boards

  • m5stack_fire: Removed unused pinctrl entries for UART2, and updated the UART1 pin mapping from GPIO32/GPIO33 to GPIO16/GPIO17 to match the documented Grove PORT.C wiring.

  • Compile definitions ‘XIP_EXTERNAL_FLASH’, ‘USE_HYPERRAM’ and ‘XIP_BOOT_HEADER_XMCD_ENABLE’ are only used in boards/nxp/mimxrt1180_evk/xip/evkmimxrt1180_flexspi_nor_config.c and boards/nxp/mimxrt1170_evk/xmcd/xmcd.c, we have changed them to local scope in the respective board CMakeLists.txt files. Applications that depended on these definitions being globally available may need to be updated. (GitHub #101322)

Device Drivers and Devicetree

ADC

  • The renesas,ra-adc compatible has been replaced by renesas,ra-adc12. Applications using the old compatible must update their devicetree nodes.

  • The renesas,ra-adc16 compatible was added. This must be used when working with the EK-RA2A1 board, which provides a 16-bit ADC resolution.

  • Renamed the CONFIG_ADC_MCUX_SAR_ADC to CONFIG_ADC_NXP_SAR_ADC.

  • Renamed the driver file from adc_mcux_sar_adc.c to drivers/adc/adc_nxp_sar_adc.c.

  • Applications using the SAR ADC driver need to update the nodes in the devicetree to include zephyr,input-positive to specify the hardware channel. For SoCs that currently support SAR ADC, the reference voltage should use ADC_REF_VDD_1 instead of ADC_REF_INTERNAL. This driver update also corrects this issue, so users also need to update the value of this property in the devicetree accordingly. (GitHub #100978)

Controller Area Network (CAN)

Counter

  • The NXP LPTMR driver (nxp,lptmr) has been updated to fix incorrect prescaler and glitch filter configuration:

    • The prescale-glitch-filter property valid range changed from [0-16] to [0-15]. The value 16 was invalid for pulse counter mode and has been removed. Device trees using value 16 must be updated to use values in the range [0-15].

    • A new boolean property prescale-glitch-filter-bypass has been introduced to explicitly control prescaler/glitch filter bypass. Previously, setting prescale-glitch-filter = <0> implicitly enabled bypass mode, which was ambiguous.

      In v4.4 and later, bypass is controlled only by the presence of prescale-glitch-filter-bypass. If the property is absent, the prescaler/glitch filter is active and prescale-glitch-filter is applied.

    • The prescaler/glitch filter behavior has been clarified:

      • In Time Counter mode: prescaler divides the clock by 2^(prescale-glitch-filter + 1)

      • In Pulse Counter mode: glitch filter recognizes change after 2^prescale-glitch-filter rising edges (value 0 is not supported for glitch filtering)

    • All in-tree device tree nodes have been updated to use prescale-glitch-filter-bypass; instead of prescale-glitch-filter = <0>;. Out-of-tree boards should be updated accordingly.

    • If both prescale-glitch-filter-bypass and prescale-glitch-filter are set, bypass mode takes precedence and the prescale-glitch-filter value is ignored.

    Example migration:

    /* Old (deprecated) */
lptmr0: counter@40040000 {
    compatible = "nxp,lptmr";
    /* Implicitly bypassed */
    prescale-glitch-filter = <0>;
};

/* New (correct) */
lptmr0: counter@40040000 {
    compatible = "nxp,lptmr";
    /* Explicitly bypassed */
    prescale-glitch-filter-bypass;
};

    Examples of using prescale-glitch-filter

    Note

    prescale-glitch-filter-bypass is a boolean. If present, bypass is enabled. If absent, bypass is disabled and prescale-glitch-filter is applied.

    In Pulse Counter mode, prescale-glitch-filter = <0> is not a supported glitch filter configuration. To request no filtering, use prescale-glitch-filter-bypass;.

    • Time Counter mode: divide the counter clock

      In Time Counter mode the prescaler divides by 2^(N + 1).

      /* Divide by 2^(0+1) = 2 */
lptmr0: counter@40040000 {
    compatible = "nxp,lptmr";
    /* Time Counter mode */
    timer-mode-sel = <0>;
    clk-source = <1>;
    clock-frequency = <32768>;
    /* /2 */
    prescale-glitch-filter = <0>;
    resolution = <16>;
};

/* Divide by 2^(3+1) = 16 */
lptmr1: counter@40041000 {
    compatible = "nxp,lptmr";
    /* Time Counter mode */
    timer-mode-sel = <0>;
    clk-source = <1>;
    clock-frequency = <32768>;
    /* /16 */
    prescale-glitch-filter = <3>;
    resolution = <16>;
};

    • Time Counter mode: explicit bypass (no division)

      lptmr0: counter@40040000 {
    compatible = "nxp,lptmr";
    /* Time Counter mode */
    timer-mode-sel = <0>;
    clk-source = <1>;
    clock-frequency = <32768>;
    /* no prescaler */
    prescale-glitch-filter-bypass;
    resolution = <16>;
};

    • Pulse Counter mode: glitch filtering

      In Pulse Counter mode the glitch filter recognizes a change after 2^N rising edges. Value 0 is not supported for glitch filtering; use bypass if you want no filtering.

      /* Recognize change after 2^2 = 4 rising edges */
lptmr0: counter@40040000 {
    compatible = "nxp,lptmr";
    /* Pulse Counter mode */
    timer-mode-sel = <1>;
    clk-source = <1>;
    input-pin = <0>;
    prescale-glitch-filter = <2>;
    resolution = <16>;
};

/* No filtering (explicit bypass) */
lptmr1: counter@40041000 {
    compatible = "nxp,lptmr";
    /* Pulse Counter mode */
    timer-mode-sel = <1>;
    clk-source = <1>;
    input-pin = <0>;
    prescale-glitch-filter-bypass;
    resolution = <16>;
};

Display

  • For ILI9XXX controllers, the usage of ILI9XXX_PIXEL_FORMAT_x in devicetrees for panel color format selection has been updated to PANEL_PIXEL_FORMAT_x. Out-of-tree boards and shields should be updated accordingly. (GitHub #99267).

  • For ILI9341 controller, display mirroring configuration has been updated to conform with the described behavior of the sample samples/drivers/display. (GitHub #99267).

Ethernet

Infineon

  • Infineon driver file names have been renamed to remove cat1 from their names to support reusability across multiple device categories. The following drivers have been renamed (GitHub #99174):

    • adc_ifx_cat1.c → adc_ifx.c

    • clock_control_ifx_cat1.c → clock_control_ifx.c

    • counter_ifx_cat1.c → counter_ifx.c

    • dma_ifx_cat1.c → dma_ifx.c

    • dma_ifx_cat1_pdl.c → dma_ifx_pdl.c

    • flash_ifx_cat1.c → flash_ifx.c

    • flash_ifx_cat1_qspi.c → flash_ifx_qspi.c

    • flash_ifx_cat1_qspi_mtb_hal.c → flash_ifx_qspi_mtb_hal.c

    • gpio_ifx_cat1.c → gpio_ifx.c

    • i2c_ifx_cat1.c → i2c_ifx.c

    • i2c_ifx_cat1_pdl.c → i2c_ifx_pdl.c

    • mbox_ifx_cat1.c → mbox_ifx.c

    • pinctrl_ifx_cat1.c → pinctrl_ifx.c

    • rtc_ifx_cat1.c → rtc_ifx.c

    • ifx_cat1_sdio.c → ifx_sdio.c

    • sdio_ifx_cat1_pdl.c → sdio_ifx_pdl.c

    • serial_ifx_cat1_uart.c → serial_ifx_uart.c

    • spi_ifx_cat1.c → spi_ifx.c

    • spi_ifx_cat1_pdl.c → spi_ifx_pdl.c

    • uart_ifx_cat1.c → uart_ifx.c

    • uart_ifx_cat1_pdl.c → uart_ifx_pdl.c

    • wdt_ifx_cat1.c → wdt_ifx.c

    Corresponding Kconfig symbols and binding files have also been updated:

    • CONFIG_*_INFINEON_CAT1 → CONFIG_*_INFINEON

    • compatible: "infineon,cat1-adc" → compatible: "infineon,adc"

MDIO

  • The mdio_bus_enable() and mdio_bus_disable() functions have been removed. MDIO bus enabling/disabling is now handled internally by the MDIO drivers. (GitHub #99690).

QSPI

  • st,stm32-qspi compatible nodes configured with dual-flash property now need to also include the ssht-enable property to reenable sample shifting. Sample shifting is configurable now and disabled by default. (GitHub #98999).

Radio

  • The following devicetree bindings have been renamed for consistency with the radio- prefix:

  • A new radio.yaml base binding has been introduced for generic radio hardware capabilities. The tx-high-power-supported property has been renamed to radio-tx-high-power-supported for consistency.

  • Device trees and overlays using the old compatible strings must be updated to use the new names.

Shell

Stepper

STM32

  • STM32 power supply configuration is now performed using Devicetree properties. New bindings st,stm32h7-pwr, st,stm32h7rs-pwr and st,stm32-dualreg-pwr have been introduced, and all Kconfig symbols related to power supply configuration have been removed:

    • CONFIG_POWER_SUPPLY_LDO

    • CONFIG_POWER_SUPPLY_DIRECT_SMPS,

    • CONFIG_POWER_SUPPLY_SMPS_1V8_SUPPLIES_LDO

    • CONFIG_POWER_SUPPLY_SMPS_2V5_SUPPLIES_LDO,

    • CONFIG_POWER_SUPPLY_SMPS_1V8_SUPPLIES_EXT_AND_LDO

    • CONFIG_POWER_SUPPLY_SMPS_2V5_SUPPLIES_EXT_AND_LDO

    • CONFIG_POWER_SUPPLY_SMPS_1V8_SUPPLIES_EXT

    • CONFIG_POWER_SUPPLY_SMPS_2V5_SUPPLIES_EXT

    • CONFIG_POWER_SUPPLY_EXTERNAL_SOURCE

  • The ST-specific chosen property /chosen/zephyr,ccm is replaced by /chosen/zephyr,dtcm. Attribute macros __ccm_data_section, __ccm_bss_section and __ccm_noinit_section are deprecated, but retained for backwards compatibility; they will be removed in Zephyr 4.5. The generic __dtcm_{data,bss,noinit}_section macros should be used instead. (GitHub #100590)

  • STM32 platforms now use the default MCUboot operating mode swap using offset (SB_CONFIG_MCUBOOT_MODE_SWAP_USING_OFFSET). To support this bootloader mode, some changes to the board devicetrees are required. Several boards already support this mode (see GitHub #100385). The previous swap using move mode can still be selected in sysbuild by enabling SB_CONFIG_MCUBOOT_MODE_SWAP_USING_MOVE.

USB

Video

  • CONFIG_VIDEO_OV7670 is now gone and replaced by CONFIG_VIDEO_OV767X. This allows supporting both the OV7670 and 0V7675.

  • CONFIG_VIDEO_BUFFER_POOL_SZ_MAX is replaced by CONFIG_VIDEO_BUFFER_POOL_HEAP_SIZE which represent the size in byte allocated for the whole video buffer pool.

Bluetooth

Bluetooth Host

  • CONFIG_BT_SIGNING has been deprecated.

  • BT_GATT_CHRC_AUTH has been deprecated.

  • bt_conn_le_info.interval has been deprecated. Use bt_conn_le_info.interval_us instead. Note that the units have changed: interval was in units of 1.25 milliseconds, while interval_us is in microseconds.

  • Legacy Bluetooth LE pairing using the passkey entry method no longer grants authenticated (MITM) protection as of the Bluetooth Core Specification v6.2. Stored bonds that were generated using this method will be downgraded to unauthenticated when loaded from persistent storage, resulting in a lower security level.

Networking

  • Networking APIs found in

    and relevant code in subsys/net etc. is namespaced. This means that either net_, NET_ or ZSOCK_ prefix is added to the network API name. This is done in order to avoid circular dependency with POSIX or libc that might define the same symbol. A compatibility header file include/zephyr/net/net_compat.h is created that provides the old symbols allowing the user to continue use the old symbols. External network applications can continue to use POSIX defined network symbols and include relevant POSIX header files like sys/socket.h to get the POSIX symbols as Zephyr networking header files will no longer include those. If the application or Zephyr internal code cannot use POSIX APIs, then the relevant network API prefix needs to be added to the code calling a network API.

Modem

Modem HL78XX

  • The Kconfig options related to HL78XX startup timing have been renamed in CONFIG_MODEM_HL78XX_DEV_* as follows:

    • MODEM_HL78XX_DEV_POWER_PULSE_DURATION → MODEM_HL78XX_DEV_POWER_PULSE_DURATION_MS

    • MODEM_HL78XX_DEV_RESET_PULSE_DURATION → MODEM_HL78XX_DEV_RESET_PULSE_DURATION_MS

    • MODEM_HL78XX_DEV_STARTUP_TIME → MODEM_HL78XX_DEV_STARTUP_TIME_MS

    • MODEM_HL78XX_DEV_SHUTDOWN_TIME → MODEM_HL78XX_DEV_SHUTDOWN_TIME_MS

  • The default startup timing was changed from 1000 ms to 120 ms to improve initialization reliability across all supported boards.

    Applications depending on the previous defaults must update their configuration.

Other subsystems

JWT

  • Previously deprecated CONFIG_JWT_SIGN_RSA_LEGACY is removed. This removal happens before the usual deprecation period of 2 releases because it has been agreed (see GitHub #97660) that Mbed TLS is an external module, so normal deprecation rules do not apply in this case.

Libsbc

  • Libsbc (sbc.c and sbc.h) is moved under the Bluetooth subsystem. The sbc.h is in include/zephyr/bluetooth now.

Tracing

  • CTF: Changed uint8_t id to uint16_t id in the CTF metadata event header. This doubles the space used for event IDs but allows 65,535 events instead of 255.

    With this change, existing CTF traces with 8-bit IDs won’t be compatible.

Settings

Modules

Trusted Firmware-M

  • The SECURE_UART1 TF-M define is now controlled by Zephyr’s CONFIG_TFM_SECURE_UART. This option will override any platform values previously specified in the TF-M repository.

Architectures