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

Device Drivers and Devicetree

Haptics

• The cirrus,cs40l5x compatible has been replaced by variant-specific compatibles cirrus,cs40l50, cirrus,cs40l51, cirrus,cs40l52, and cirrus,cs40l53. Applications using the old compatible must update their devicetree nodes accordingly.

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.

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.

Ethernet

• ETHERNET_CONFIG_TYPE_T1S_PARAM and the related NET_REQUEST_ETHERNET_SET_T1S_PARAM has been removed. phy_set_plca_cfg() together with net_eth_get_phy() should be used instead to set these parameters (GitHub #108136).

• In the functions implemented by the ethernet_api 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 pinctrl-0 and pinctrl-names devicetree properties for the nxp,enet-mac need to be moved from the MAC node to the parent Ethernet controller node. (GitHub #107352)

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)

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.

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.

STM32

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

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)

Bluetooth

Bluetooth Audio

• BAP

  • bt_bap_stream.codec_cfg is now const, to better reflect that it is a read-only value. Any non-read uses of it will need to be updated with the appropriate operations such as bt_bap_stream_config(), bt_bap_stream_reconfig(), bt_bap_stream_enable() or bt_bap_stream_metadata(). (GitHub #104219)

  • bt_bap_stream.qos is now const, to better reflect that it is a read-only value. Any non-read uses of it will need to be set with the appropriate operations such as bt_bap_unicast_group_create(), bt_bap_unicast_group_reconfig(), bt_bap_broadcast_source_create() or bt_bap_broadcast_source_reconfig(). (GitHub #104887)

  • Almost all API uses of struct bt_bap_qos_cfg * are now const, which means that once the qos has been stored in a parameter struct like bt_bap_broadcast_source_param or bt_bap_unicast_group_stream_param, then the parameter’s pointer cannot be used to modify the qos, and the actual definition of the struct should be modified instead. (GitHub #104219)

  • bt_bap_unicast_group_info.sink_pd and bt_bap_unicast_group_info.source_pd now reflect the local values defined for the group, and not the values configured for any remote ASEs. (GitHub #104887)

  • bt_bap_unicast_client_discover() and bt_bap_broadcast_assistant_discover() now require that the connection has already gone through the pairing process and meets the security requirements of BAP before doing any discovery. In most cases this requires a call to bt_conn_set_security() for new devices. Bonded devices that reconnect should not require anything.

  • Almost all API uses of struct bt_audio_codec_cfg * are now const, which means that once the codec_cfg has been stored in a parameter struct like bt_bap_stream or bt_bap_broadcast_source_subgroup_param, then the parameter’s pointer cannot be used to modify the codec_cfg, and the actual definition of the struct should be modified instead. (GitHub #104219)

• CAP

  • bt_cap_commander_broadcast_reception_start() now waits for the CAP acceptors to sync to the broadcast before completing. This means that if the broadcast source is offline, including colocated broadcast sources like the ones created by bt_cap_handover_unicast_to_broadcast(), shall be active and have the periodic advertising enabled with a configured BASE. For bt_cap_handover_unicast_to_broadcast() the newly added bt_cap_handover_cb.unicast_to_broadcast_created can be used to configure the BASE. This also means that any current checks implemented by an application to wait for receive state updates indicating successful sync can be removed, as bt_cap_commander_broadcast_reception_start() now ensures this when bt_cap_commander_cb.broadcast_reception_start is called. This also applies for bt_cap_commander_broadcast_reception_stop() in a similar manner. (GitHub #101070)

• CCP

  • bt_tbs_client_cb.technology has changed the value parameter from uint32_t to enum bt_bearer_tech. Applications using this application should switch the type. (GitHub #102430)

  • All BT_TBS_TECHNOLOGY_* values like BT_TBS_TECHNOLOGY_3G are renamed to BT_BEARER_TECH_* like BT_BEARER_TECH_3G. Applications can do search-and-replace from BT_TBS_TECHNOLOGY to BT_BEARER_TECH. Additionally the values are now defined in include/zephyr/bluetooth/assigned_numbers.h instead of include/zephyr/bluetooth/audio/tbs.h. (GitHub #102430)

• CSIP

  • Optional CSIS characteristics have been made configurable via Kconfig and must be enabled explicitly:

    • Coordinated Set Size → CONFIG_BT_CSIP_SET_MEMBER_SIZE_SUPPORT

    • Set Member Lock → CONFIG_BT_CSIP_SET_MEMBER_LOCK_SUPPORT

    • Set Member Rank → CONFIG_BT_CSIP_SET_MEMBER_RANK_SUPPORT

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

Ethernet

• CONFIG_NET_DEFAULT_IF_ETHERNET now allows to get the first ethernet interface, instead of the first between ethernet and wifi.

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)

Modules

• Support for the CANopenNode protocol stack was moved to an external module.

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

• CONFIG_MBEDTLS_SSL_EARLY_DATA is now an explicit opt-in and is no longer implicitly enabled by CONFIG_MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_ENABLED. Out-of-tree applications or board configurations that rely on TLS 1.3 PSK early data (0-RTT) must now explicitly enable CONFIG_MBEDTLS_SSL_EARLY_DATA.

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.