Migration guide to Zephyr v3.5.0 (Working Draft)¶
This document describes the changes required or recommended when migrating your application from Zephyr v3.4.0 to Zephyr v3.5.0.
Required changes¶
The kernel
k_mem_slab_free()
function has changed its signature, now taking avoid *mem
pointer instead of avoid **mem
double-pointer. The new signature will not immediately trigger a compiler error or warning, instead likely causing a invalid memory access at runtime. A new_ASSERT
statement, that you can enable withCONFIG_ASSERT
, will detect if you pass the function memory not belonging to the memory blocks in the slab.The
CONFIG_BOOTLOADER_SRAM_SIZE
default value is now0
(was16
). Bootloaders that use a part of the SRAM should set this value to an appropriate size. GitHub #60371The Kconfig option
CONFIG_GPIO_NCT38XX_INTERRUPT
has been renamed toCONFIG_GPIO_NCT38XX_ALERT
.MCUmgr SMP version 2 error codes entry has changed due to a collision with an existing response in shell_mgmt. Previously, these errors had the entry
ret
but now have the entryerr
.smp_add_cmd_ret()
is now deprecated andsmp_add_cmd_err()
should be used instead,MGMT_CB_ERROR_RET
is now deprecated andMGMT_CB_ERROR_ERR
should be used instead. SMP version 2 error code defines for in-tree modules have been updated to replace the*_RET_RC_*
parts with*_ERR_*
.MCUmgr SMP version 2 error translation (to legacy MCUmgr error code) is now handled in function handlers by setting the
mg_translate_error
function pointer ofmgmt_group
when registering a group. Seesmp_translate_error_fn
for function details. Any SMP version 2 handlers made for Zephyr 3.4 need to be updated to include these translation functions when the groups are registered.zephyr,memory-region-mpu
was renamedzephyr,memory-attr
and its type moved from ‘enum’ to ‘int’. To have a seamless conversion this is the required change in the DT:- "RAM" -> <( DT_MEM_ARM(ATTR_MPU_RAM) )> - "RAM_NOCACHE" -> <( DT_MEM_ARM(ATTR_MPU_RAM_NOCACHE) )> - "FLASH" -> <( DT_MEM_ARM(ATTR_MPU_FLASH) )> - "PPB" -> <( DT_MEM_ARM(ATTR_MPU_PPB) )> - "IO" -> <( DT_MEM_ARM(ATTR_MPU_IO) )> - "EXTMEM" -> <( DT_MEM_ARM(ATTR_MPU_EXTMEM) )>
A new networking Kconfig option
CONFIG_NET_INTERFACE_NAME
defaults toy
. The option allows user to set a name to a network interface. During system startup a default name is assigned to the network interface likeeth0
to the first Ethernet network interface. The option affects the behavior ofSO_BINDTODEVICE
BSD socket option. If the Kconfig option is set ton
, which is how the system worked earlier, then the name of the device assigned to the network interface is used by theSO_BINDTODEVICE
socket option. If the Kconfig option is set toy
(current default), then the network interface name is used by theSO_BINDTODEVICE
socket option.On all STM32 ADC, it is no longer possible to read sensor channels (Vref, Vbat or temperature) using the ADC driver. The dedicated sensor driver should be used instead. This change is due to a limitation on STM32F4 where the channels for temperature and Vbat are identical, and the impossibility of determining what we want to measure using solely the ADC API.
The default C library used on most targets has changed from the built-in minimal C library to Picolibc. While both provide standard C library interfaces and shouldn’t cause any behavioral regressions for applications, there are a few side effects to be aware of when migrating to Picolibc.
Picolibc enables thread local storage (
CONFIG_THREAD_LOCAL_STORAGE
) where supported. This changes some internal operations within the kernel that improve performance using some TLS variables. Zephyr places TLS variables in the memory reserved for the stack, so stack usage for every thread will increase by 8-16 bytes.Picolibc uses the same malloc implementation as the minimal C library, but the default heap size depends on which C library is in use. When using the minimal C library, the default heap is zero bytes, which means that malloc will always fail. When using Picolibc, the default is 16kB with
CONFIG_MMU
orARCH_POSIX
, 2kB withCONFIG_USERSPACE
andCONFIG_MPU_REQUIRES_POWER_OF_TWO_ALIGNMENT
. For all other targets, the default heap uses all remaining memory on the system. You can change this by adjustingCONFIG_COMMON_LIBC_MALLOC_ARENA_SIZE
.Picolibc can either be built as part of the OS build or pulled from the toolchain. When building as part of the OS, the build will increase by approximately 1000 files.
When using the standard C++ library with Picolibc, both of those must come from the toolchain as the standard C++ library depends upon the C library ABI.
Picolibc removes the
-ffreestanding
compiler option. This allows significant compiler optimization improvements, but also means that the compiler will now warn about declarations of main which don’t conform to the Zephyr required type –int main(void)
.Picolibc’s default floating point input/output code is larger than the minimal C library version (this is necessary to conform with the C language “round trip” requirements for these operations). If you use
CONFIG_CBPRINTF_FP_SUPPORT
, you will see increased memory usage unless you also disableCONFIG_PICOLIBC_IO_FLOAT_EXACT
, which switches Picolibc to a smaller, but inexact conversion algorithm. This requires building Picolibc as a module.
The CAN controller timing API functions
can_set_timing()
andcan_set_timing_data()
no longer fallback to the (Re-)Synchronization Jump Width (SJW) value set in the devicetree properties for the given CAN controller upon encountering an SJW value corresponding toCAN_SJW_NO_CHANGE
(which is no longer available). The caller will therefore need to fill in thesjw
field incan_timing
. To aid in this, thecan_calc_timing()
andcan_calc_timing_data()
functions now automatically calculate a suitable SJW. The calculated SJW can be overwritten by the caller if needed. The CAN controller API functionscan_set_bitrate()
andcan_set_bitrate_data()
now also automatically calculate a suitable SJW, but their SJW cannot be overwritten by the caller.Ethernet PHY devicetree bindings were updated to use the standard
reg
property for the PHY address instead of a customaddress
property. As a result, MDIO controller nodes now require#address-cells
and#size-cells
properties. Similarly, Ethernet PHY devicetree nodes and corresponding driver were updated to consistently use the node nameethernet-phy
instead ofphy
. Devicetrees and overlays must be updated accordingly:mdio { compatible = "mdio-controller"; #address-cells = <1>; #size-cells = <0>; ethernet-phy@0 { compatible = "ethernet-phy"; reg = <0>; }; };
The
accept()
callback’s signature inbt_l2cap_server
has changed toint (*accept)(struct bt_conn *conn, struct bt_l2cap_server *server, struct bt_l2cap_chan **chan)
, adding a newserver
parameter pointing to thebt_l2cap_server
structure instance the callback relates to. GitHub #60536
Recommended Changes¶
Setting the GIC architecture version by selecting
CONFIG_GIC_V1
,CONFIG_GIC_V2
andCONFIG_GIC_V3
directly in Kconfig has been deprecated. The GIC version should now be specified by adding the appropriate compatible, for examplearm,gic-v2
, to the GIC node in the device tree.Nordic nRF based boards using
CONFIG_NFCT_PINS_AS_GPIOS
to configure NFCT pins as GPIOs, should instead set the new UICRnfct-pins-as-gpios
property in devicetree. It can be set like this in the board devicetree files:&uicr { nfct-pins-as-gpios; };
Nordic nRF based boards using
CONFIG_GPIO_AS_PINRESET
to configure reset GPIO as nRESET, should instead set the new UICRgpio-as-nreset
property in devicetree. It can be set like this in the board devicetree files:&uicr { gpio-as-nreset; };
The
CONFIG_MODEM_GSM_PPP
modem driver is obsolete. Instead the newCONFIG_MODEM_CELLULAR
driver should be used. As part of thisCONFIG_GSM_MUX
andCONFIG_UART_MUX
are being marked as deprecated as well. The new modem subsystemCONFIG_MODEM_CMUX
andCONFIG_MODEM_PPP`
should be used instead.Device drivers should now be restricted to
PRE_KERNEL_1
,PRE_KERNEL_2
andPOST_KERNEL
initialization levels. Other device initialization levels, includingEARLY
,APPLICATION
, andSMP
, have been deprecated and will be removed in future releases. Note that these changes do not apply to initialization levels used in the context of theinit.h
API, e.g.SYS_INIT
.The following CAN controller devicetree properties are now deprecated in favor specifying the initial CAN bitrate using the
bus-speed
,sample-point
,bus-speed-data
, andsample-point-data
properties: *sjw
*prop-seg
*phase-seg1
*phase-seg1
*sjw-data
*prop-seg-data
*phase-seg1-data
*phase-seg1-data