Migration guide to Zephyr v4.0.0 (Working Draft)
This document describes the changes required when migrating your application from Zephyr v3.7.0 to Zephyr v4.0.0.
Any other changes (not directly related to migrating applications) can be found in the release notes.
Build System
Removed the
CONFIG_MCUBOOT_CMAKE_WEST_SIGN_PARAMS
Kconfig option aswest sign
is no longer called by the build system when signing images for MCUboot.The imgtool part of
west sign
has been deprecated, options to be supplied to imgtool when signing should be set inCONFIG_MCUBOOT_EXTRA_IMGTOOL_ARGS
instead.
Kernel
Removed the deprecated
CONFIG_MP_NUM_CPUS
, application should be updated to useCONFIG_MP_MAX_NUM_CPUS
instead.
Boards
native_posix has been deprecated in favour of native_sim (GitHub #76898).
Nordic nRF53 and nRF91 based boards can use the common devicetree overlays in
dts/common/nordic
to define default flash and ram partitioning based on TF-M.STM32WBA: The command used for fetching blobs required to build ble applications is now
west blobs fetch hal_stm32
instead ofwest blobs fetch stm32
.Board
qemu_xtensa
is deprecated. Useqemu_xtensa/dc233c
instead.
Devicetree
The
DT_REG_ADDR
macro and its variants are now expanding into an unsigned literals (i.e. with aU
suffix). To use addresses as devicetree indexes use theDT_REG_ADDR_RAW
variants.The
DT_REG_SIZE
macro and its variants are also expanding into unsigned literals, no raw variants are provided at this stage.
STM32
On all official STM32 boards,
west flash
selects STM32CubeProgrammer as the default west runner. If you want to enforce the selection of another runner like OpenOCD or pyOCD for flashing, you should specify it using the west--runner
or-r
option. (GitHub #75284)ADC: Domain clock needs to be explicitly defined if property st,adc-clock-source = <ASYNC> is used.
Modules
Mbed TLS
The Kconfig options
CONFIG_MBEDTLS_TLS_VERSION_1_0
andCONFIG_MBEDTLS_TLS_VERSION_1_1
have been removed because Mbed TLS doesn’t support TLS 1.0 and 1.1 anymore since v3.0. (GitHub #76833)The following Kconfig symbols were renamed (GitHub #76408): *
CONFIG_MBEDTLS_ENTROPY_ENABLED
is nowCONFIG_MBEDTLS_ENTROPY_C
, *CONFIG_MBEDTLS_ZEPHYR_ENTROPY
is nowCONFIG_MBEDTLS_ENTROPY_POLL_ZEPHYR
.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. (GitHub #77657)
TinyCrypt
Albeit the formal deprecation of TinyCrypt is not started yet, its removal from the Zephyr codebase is. Formal deprecation will happen in the next release.
Trusted Firmware-M
The security counter used for the hardware rollback protection now comes explicitly from
CONFIG_TFM_IMAGE_SECURITY_COUNTER
, instead of being automatically determined from the image version. This has been changed as the implicit counter calculation is incompatible with versions larger than0.0.1024
(GitHub #78128).
LVGL
zcbor
Updated the zcbor library to version 0.9.0. Full release notes at https://github.com/NordicSemiconductor/zcbor/blob/0.9.0/RELEASE_NOTES.md Migration guide at https://github.com/NordicSemiconductor/zcbor/blob/0.9.0/MIGRATION_GUIDE.md Migration guide copied here:
zcbor_simple_*()
functions have been removed to avoid confusion about their use. They are still in the C file because they are used by other functions. Instead, use the specific functions for the currently supported simple values, i.e.zcbor_bool_*()
,zcbor_nil_*()
, andzcbor_undefined_*()
. If a removed variant is strictly needed, add your own forward declaration in your code.Code generation naming:
More C keywords are now capitalized to avoid naming collision. You might have to capitalize some instances if your code was generated to have those names.
A fix was made to the naming of bstr elements with a .size specifier, which might mean that these elements change name in your code when you regenerate.
Device Drivers and Devicetree
The
compatible
of the LiteX ethernet controller has been renamed fromlitex,eth0
tolitex,liteeth
. (GitHub #75433)The
compatible
of the LiteX uart controller has been renamed fromlitex,uart0
tolitex,uart
. (GitHub #74522)The devicetree bindings for the Microchip
mcp23xxx
series have been split up. Users ofmicrochip,mcp230xx
andmicrochip,mcp23sxx
should change their devicetreecompatible
values to the specific chip variant, e.g.microchip,mcp23017
. Thengpios
devicetree property has been removed, since it is implied by the model name. Chip variants with open-drain outputs (mcp23x09
,mcp23x18
) now correctly reflect this in their driver API, users of these devices should ensure they pass appropriate values togpio_pin_set()
. (GitHub #65797)The
power-domain
property has been removed in favor ofpower-domains
. The new property allows to add more than one power domain.power-domain-names
is also available to optionally name each entry inpower-domains
. The number of cells in thepower-domains
property need to be defined using#power-domain-cells
.
Analog Digital Converter (ADC)
For all STM32 ADC that selects an asynchronous clock through
st,adc-clock-source
property, it is now mandatory to also explicitly define a domain clock source using theclock
property.
Clock control
LFXO/HFXO (High/Low Frequency Crystal Oscillator) present in nRF53 series can now be configured using devicetree. The Kconfig options
CONFIG_SOC_ENABLE_LFXO
,CONFIG_SOC_LFXO_CAP_EXTERNAL
,CONFIG_SOC_LFXO_CAP_INT_6PF
,CONFIG_SOC_LFXO_CAP_INT_7PF
,CONFIG_SOC_LFXO_CAP_INT_9PF
,CONFIG_SOC_HFXO_CAP_DEFAULT
,CONFIG_SOC_HFXO_CAP_EXTERNAL
,CONFIG_SOC_HFXO_CAP_INTERNAL
andCONFIG_SOC_HFXO_CAP_INT_VALUE_X2
have been deprecated.LFXO can now be configured like this:
/* use external capacitors */ &lfxo { load-capacitors = "external"; }; /* use internal capacitors (value needs to be selected: 6, 7, 9pF) &lfxo { load-capacitors = "internal"; load-capacitance-picofarad = <...>; };
HFXO can now be configured like this:
/* use external capacitors */ &hfxo { load-capacitors = "external"; }; /* use internal capacitors (value needs to be selected: 7pF...20pF in 0.5pF * steps, units: femtofarads) */ &hfxo { load-capacitors = "internal"; load-capacitance-femtofarad = <...>; };
Crypto
Following the deprecation of the TinyCrypt library (GitHub #79566), the TinyCrypt-based shim driver was marked as deprecated (GitHub #79653).
Display
Disk
The SDMMC subsystem driver now requires a
disk-name
property be supplied with the definition of the disk, which is used when registering the SD device with the disk subsystem. This permits multiple SD devices to be registered simultaneously. If unsure,disk-name = "SD"
may be used as a sane default.The MMC subsystem driver now requires a
disk-name
property be supplied with the definition of the disk, which is used when registering the MMC device with the disk subsystem. This permits multiple MMC devices to be registered simultaneously. If unsure,disk-name = "SD2"
may be used as a sane default.
Enhanced Serial Peripheral Interface (eSPI)
GNSS
The u-blox M10 driver has been renamed to M8 as it only supports M8 based devices. Existing devicetree compatibles should be updated to
u-blox,m8
, and Kconfig symbols swapped toCONFIG_GNSS_U_BLOX_M8
.The APIs
gnss_set_periodic_config()
andgnss_get_periodic_config()
have been removed. (GitHub #76392)
Input
INPUT_CALLBACK_DEFINE
has now an extrauser_data
void pointer argument that can be used to reference any user data structure. To restore the current behavior it can be set toNULL
. Avoid *user_data
argument has to be added to the callback function arguments.The
analog-axis
invert
property has been renamed toinvert-input
(there’s now aninvert-output
available as well).
Interrupt Controller
LED Strip
PWM
The Raspberry Pi Pico PWM driver now configures frequency adaptively. This has resulted in a change in how device tree parameters are handled. If the
raspberry,pico-pwm
’sdivider-int-0
or variations for each channel are specified, or if these are set to 0, the driver dynamically configures the division ratio by specified cycles. The driver will operate at the specified division ratio if a non-zero value is specified fordivider-int-0
. This is unchanged from previous behavior. Please specifydivider-int-0
explicitly to make the same behavior as before.
SDHC
The NXP USDHC driver now assumes a card is present if no card detect method is configured, instead of using the peripheral’s internal card detect signal to check for card presence. To use the internal card detect signal, the devicetree property
detect-cd
should be added to the USDHC node in use.
Sensors
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 themicrochip,mcp9808
string.The
current-sense-amplifier
sense resistor is now specified in milli-ohms (sense-resistor-milli-ohms
) instead of micro-ohms in order to increase the maximum representable resistor from 4.2k to 4.2M.The
current-sense-amplifier
propertiessense-gain-mult
andsense-gain-div
are now limited to a maximum value ofUINT16_MAX
to enable smaller rounding errors in internal calculations.The
nxp,
prefixed properties innxp,kinetis-acmp
have been deprecated in favor of properties without the prefix. The sensor based driver for thenxp,kinetis-acmp
has been updated to support both the new and deprecated property names. Uses of the deprecated property names should be updated to the new property names.
Serial
Users of
uart_irq_tx_ready()
now need to check forret > 0
to ensure that the FIFO can accept data bytes, instead ofret == 1
. The function now returns a lower bound on the number of bytes that can be provided touart_fifo_fill()
without truncation.LiteX:
CONFIG_UART_LITEUART
has been renamed toCONFIG_UART_LITEX
.
Regulator
Internal regulators present in nRF52/53 series can now be configured using devicetree. The Kconfig options
CONFIG_SOC_DCDC_NRF52X
,CONFIG_SOC_DCDC_NRF52X_HV
,CONFIG_SOC_DCDC_NRF53X_APP
,CONFIG_SOC_DCDC_NRF53X_NET
andCONFIG_SOC_DCDC_NRF53X_HV
selected by board-level Kconfig options have been deprecated.Example for nRF52 series:
/* configure REG/REG1 in DC/DC mode */ ®/reg1 { regulator-initial-mode = <NRF5X_REG_MODE_DCDC>; }; /* enable REG0 (HV mode) */ ®0 { status = "okay"; };
Example for nRF53 series:
/* configure VREGMAIN in DC/DC mode */ &vregmain { regulator-initial-mode = <NRF5X_REG_MODE_DCDC>; }; /* configure VREGRADIO in DC/DC mode */ &vregradio { regulator-initial-mode = <NRF5X_REG_MODE_DCDC>; }; /* enable VREGH (HV mode) */ &vregh { status = "okay"; };
Bluetooth
Bluetooth HCI
The
bt-hci-bus
andbt-hci-quirks
devicetree properties for HCI bindings have been changed to use lower-case strings without theBT_HCI_QUIRK_
andBT_HCI_BUS_
prefixes.The Kconfig option
BT_SPI
is now automatically selected based on devicetree compatibles and can be removed from board.defconfig
files.
Bluetooth Mesh
Bluetooth Audio
The Volume Renderer callback functions
bt_vcp_vol_rend_cb.state
andbt_vcp_vol_rend_cb.flags
for VCP now contain an additional parameter for the connection. This needs to be added to all instances of VCP Volume Renderer callback functions defined. (GitHub #76992)The Unicast Server has a new registration function
bt_bap_unicast_server_register()
which takes abt_bap_unicast_server_register_param
as argument. This allows the Unicast Server to dynamically register Source and Sink ASE count at runtime. The oldCONFIG_BT_ASCS_ASE_SRC_COUNT
andCONFIG_BT_ASCS_ASE_SNK_COUNT
has been renamed toCONFIG_BT_ASCS_MAX_ASE_SRC_COUNT
andCONFIG_BT_ASCS_MAX_ASE_SNK_COUNT
to reflect that they now serve as a compile-time maximum configuration of ASEs to be used.bt_bap_unicast_server_register()
needs to be called once before using the Unicast Server, and more specfically prior to callingbt_bap_unicast_server_register_cb()
for the first time. It does not need to be called again until the new functionbt_bap_unicast_server_unregister()
has been called. (GitHub #76632)The Coordinated Set Coordinator functions
bt_csip_set_coordinator_lock()
andbt_csip_set_coordinator_release()
now require thatCONFIG_BT_BONDABLE
is enabled and that all members are bonded, to comply with the requirements from the CSIP spec. (GitHub #78877)The callback structure provided to
bt_bap_unicast_client_register_cb()
is no longerconst
, and now multiple callback structures can be registered. (GitHub #78999)The Broadcast Audio Scan Service (BASS) shall now be registered and unregistered dynamically at runtime within the scan delegator. Two new APIs,
bt_bap_scan_delegator_register()
andbt_bap_scan_delegator_unregister()
, have been introduced to manage both BASS and scan delegator registration and initialization dynamically. It should also be mentioned that the previous callback registration function,bt_bap_scan_delegator_register_cb()
has now been removed and merged withbt_bap_scan_delegator_register()
. This change allows more flexibility when registering or unregistering scan delegator and BASS related functionality without requiring build-time configuration. Existing need to be updated to use these new APIs. (GitHub #78751)The Telephone Bearer Service (TBS) and Generic Telephone Bearer Service (GTBS) shall now be registered dynamically at runtime with
bt_tbs_register_bearer()
. The services can also be unregistered withbt_tbs_unregister_bearer()
. (GitHub #76108)There has been a rename from
bt_audio_codec_qos
tobt_bap_qos_cfg
. This effects all structs, enums and defines that used thebt_audio_codec_qos
name. To use the new naming simply do a search-and-replace forbt_audio_codec_qos
tobt_bap_qos_cfg
andBT_AUDIO_CODEC_QOS
toBT_BAP_QOS_CFG
. (GitHub #76633)The generation of broadcast ID inside of zephyr stack has been removed, it is now up the application to generate a broadcast ID. This means that the application can now fully decide whether to use a static or random broadcast ID. Reusing and statically defining a broadcast ID was added to the Basic Audio Profile in version 1.0.2, which is the basis for this change. All instances of
bt_cap_initiator_broadcast_get_id()
andbt_bap_broadcast_source_get_id()
has been removed(GitHub #80228)BT_AUDIO_BROADCAST_CODE_SIZE
has been removed andBT_ISO_BROADCAST_CODE_SIZE
should be used instead. (GitHub #80217)
Bluetooth Classic
Bluetooth Host
Automatic advertiser resumption is deprecated
Note
This deprecation is compiler-checked. If you get no warnings, you should not be affected.
- Deprecated symbols:
- New symbols:
BT_LE_ADV_OPT_CONNECTABLE
is a combined
instruction to make the advertiser connectable and to enable
automatic resumption. To disable the automatic resumption, use
BT_LE_ADV_OPT_CONN
.
Extended Advertising API with shorthands
Extended Advertising API bt_le_ext_adv_*
implicitly assumes
BT_LE_ADV_OPT_ONE_TIME
and never automatically
resume advertising. Therefore, the following search/replace can
be applied without thinking:
Replace all
-bt_le_ext_adv_create(BT_LE_ADV_CONN, ...)
+bt_le_ext_adv_create(BT_LE_ADV_FAST_2, ...)
-bt_le_ext_adv_update_param(..., BT_LE_ADV_CONN)
+bt_le_ext_adv_update_param(..., BT_LE_ADV_FAST_2)
Extended Advertising API with custom parameters
You may have uses of BT_LE_ADV_OPT_CONNECTABLE
in assignments to a bt_le_adv_param
. If your struct
is never passed to bt_le_adv_start()
, you should:
replace
BT_LE_ADV_OPT_CONNECTABLE
withBT_LE_ADV_OPT_CONN
.remove
BT_LE_ADV_OPT_ONE_TIME
.
Legacy Advertising API not using automatic resumption
Any calls to bt_le_adv_start()
that use the combination
BT_LE_ADV_OPT_CONNECTABLE
and
BT_LE_ADV_OPT_ONE_TIME
should have that
combination replaced with BT_LE_ADV_OPT_CONN
.
Legacy Advertising API using automatic resumption
For this case, the application has to take over the responsibility of restarting the advertiser.
Refer to the extended advertising sample for an example implementation of advertiser restarting. The same technique can be used for legacy advertising.
Bluetooth Crypto
Networking
The CoAP public API functions
coap_get_block1_option()
andcoap_get_block2_option()
have changed. Theblock_number
pointer type has changed fromuint8_t *
touint32_t *
. Additionally,coap_get_block2_option()
now accepts an additionalbool *has_more
parameter, to store the value of the more flag. (GitHub #76052)The struct
coap_transmission_parameters
has a new fieldack_random_percent
ifCONFIG_COAP_RANDOMIZE_ACK_TIMEOUT
is enabled. (GitHub #79058)The Ethernet bridge shell is moved under network shell. This is done so that all the network shell activities can be found under
net
shell command. After this change the bridge shell is used bynet bridge
command. (GitHub #77235)The Ethernet bridging code is changed to allow similar configuration experience as in Linux. The bridged Ethernet interface can be used normally even if bridging is enabled. The actual bridging is done by a separate virtual network interface that directs network packets to bridged Ethernet interfaces. The
eth_bridge_iface_allow_tx()
is removed as it is not needed because the bridged Ethernet interface can send and receive data normally. Theeth_bridge_listener_add()
andeth_bridge_listener_remove()
are removed as same functionality can be achieved using promiscuous API. Because the bridge interface is a normal network interface, theeth_bridge_iface_add()
andeth_bridge_iface_remove()
will take network interface pointer as a first parameter. (GitHub #77987)To facilitate use outside of the networking subsystem, the network buffer header file was renamed from include/zephyr/net/buf.h to include/zephyr/net_buf.h and the implementation moved to lib/net_buf/. (GitHub #78009)
The
work_q
parameter toNET_SOCKET_SERVICE_SYNC_DEFINE
andNET_SOCKET_SERVICE_SYNC_DEFINE_STATIC
has been removed as it was always ignored. (GitHub #79446)The callback function for the socket service has changed. The
struct k_work *work
parameter has been replaced with a pointer to thestruct net_socket_service_event *pev
parameter. (GitHub #80041)Deprecated the
CONFIG_NET_SOCKETS_POLL_MAX
option in favour ofCONFIG_ZVFS_POLL_MAX
.
Other Subsystems
Flash map
CONFIG_SPI_NOR_IDLE_IN_DPD
has been removed from theCONFIG_SPI_NOR
driver. An enhanced version of this functionality can be obtained by enabling Device Runtime Power Management on the device (Tunable withCONFIG_SPI_NOR_ACTIVE_DWELL_MS
).
hawkBit
hawkbit_autohandler()
now takes one argument. This argument has to be set totrue
for the same behavior as before the change. (GitHub #71037)<zephyr/mgmt/hawkbit.h>
is deprecated in favor of<zephyr/mgmt/hawkbit/hawkbit.h>
. The old header will be removed in future releases and its usage should be avoided. The hawkbit autohandler has been separated into<zephyr/mgmt/hawkbit/autohandler.h>
. The configuration part of hawkbit is now in<zephyr/mgmt/hawkbit/config.h>
. (GitHub #71037)
MCUmgr
The
MCUMGR_TRANSPORT_BT_AUTHEN
Kconfig option from theCONFIG_MCUMGR_TRANSPORT_BT
MCUmgr transport has been replaced with theCONFIG_MCUMGR_TRANSPORT_BT_PERM_RW
Kconfig choice. The requirement for Bluetooth authentication is now indicated by theCONFIG_MCUMGR_TRANSPORT_BT_PERM_RW_AUTHEN
Kconfig option. To remove the default requirement for Bluetooth authentication it is necessary to enable theCONFIG_MCUMGR_TRANSPORT_BT_PERM_RW
Kconfig option in the project configuration.
Modem
Random
Following the deprecation of the TinyCrypt library (GitHub #79566), usage of TinyCrypt in the CTR-DRBG random number generator was removed. From now on Mbed TLS is required to enable
CONFIG_CTR_DRBG_CSPRNG_GENERATOR
. (GitHub #79653)
Shell
kernel threads
andkernel stacks
shell command have been renamed tokernel thread list
&kernel thread stacks
JWT (JSON Web Token)
By default, the signature is now computed using the PSA Crypto API for both RSA and ECDSA (GitHub #78243). The conversion to the PSA Crypto API is part of the adoption of a standard interface for crypto operations (GitHub #43712). Moreover, following the deprecation of the TinyCrypt library (GitHub #79566), usage of TinyCrypt was removed from the JWT subsystem (GitHub #79653).
The following new symbols were added to allow specifying both the signature algorithm and crypto library:
CONFIG_JWT_SIGN_RSA_PSA
(default) RSA signature using the PSA Crypto API;CONFIG_JWT_SIGN_RSA_LEGACY
RSA signature using Mbed TLS;CONFIG_JWT_SIGN_ECDSA_PSA
ECDSA signature using the PSA Crypto API.
They replace the previously-existing Kconfigs
CONFIG_JWT_SIGN_RSA
andCONFIG_JWT_SIGN_ECDSA
. (GitHub #79653)