1:orphan: 2 3.. _migration_3.5: 4 5Migration guide to Zephyr v3.5.0 6################################ 7 8This document describes the changes required or recommended when migrating your 9application from Zephyr v3.4.0 to Zephyr v3.5.0. 10 11Any other changes (not directly related to migrating applications) can be found in 12the :ref:`release notes<zephyr_3.5>`. 13 14Required changes 15**************** 16 17Kernel 18====== 19 20* The kernel :c:func:`k_mem_slab_free` function has changed its signature, now 21 taking a ``void *mem`` pointer instead of a ``void **mem`` double-pointer. 22 The new signature will not immediately trigger a compiler error or warning, 23 instead likely causing a invalid memory access at runtime. A new ``_ASSERT`` 24 statement, that you can enable with :kconfig:option:`CONFIG_ASSERT`, will 25 detect if you pass the function memory not belonging to the memory blocks in 26 the slab. 27 28* :c:macro:`CONTAINER_OF` now performs type checking, this was very commonly 29 misused to obtain user structure from :c:struct:`k_work` pointers without 30 passing from :c:struct:`k_work_delayable`. This would now result in a build 31 error and have to be done correctly using 32 :c:func:`k_work_delayable_from_work`. 33 34C Library 35========= 36 37* The default C library used on most targets has changed from the built-in 38 minimal C library to Picolibc. While both provide standard C library 39 interfaces and shouldn't cause any behavioral regressions for applications, 40 there are a few side effects to be aware of when migrating to Picolibc. 41 42 * Picolibc enables thread local storage 43 (:kconfig:option:`CONFIG_THREAD_LOCAL_STORAGE`) where supported. This 44 changes some internal operations within the kernel that improve 45 performance using some TLS variables. Zephyr places TLS variables in the 46 memory reserved for the stack, so stack usage for every thread will 47 increase by 8-16 bytes. 48 49 * Picolibc uses the same malloc implementation as the minimal C library, but 50 the default heap size depends on which C library is in use. When using the 51 minimal C library, the default heap is zero bytes, which means that malloc 52 will always fail. When using Picolibc, the default is 16kB with 53 :kconfig:option:`CONFIG_MMU` or :kconfig:option:`ARCH_POSIX`, 2kB with 54 :kconfig:option:`CONFIG_USERSPACE` and 55 :kconfig:option:`CONFIG_MPU_REQUIRES_POWER_OF_TWO_ALIGNMENT`. For all 56 other targets, the default heap uses all remaining memory on the system. 57 You can change this by adjusting 58 :kconfig:option:`CONFIG_COMMON_LIBC_MALLOC_ARENA_SIZE`. 59 60 * Picolibc can either be built as part of the OS build or pulled from the 61 toolchain. When building as part of the OS, the build will increase by 62 approximately 1000 files. 63 64 * When using the standard C++ library with Picolibc, both of those must come 65 from the toolchain as the standard C++ library depends upon the C library 66 ABI. 67 68 * Picolibc removes the ``-ffreestanding`` compiler option. This allows 69 significant compiler optimization improvements, but also means that the 70 compiler will now warn about declarations of `main` which don't conform to 71 the Zephyr required type -- ``int main(void)``. 72 73 * Picolibc's default floating point input/output code is larger than the 74 minimal C library version (this is necessary to conform with the C 75 language "round trip" requirements for these operations). If you use 76 :kconfig:option:`CONFIG_CBPRINTF_FP_SUPPORT`, you will see increased 77 memory usage unless you also disable 78 :kconfig:option:`CONFIG_PICOLIBC_IO_FLOAT_EXACT`, which switches Picolibc 79 to a smaller, but inexact conversion algorithm. This requires building 80 Picolibc as a module. 81 82Device Drivers and Device Tree 83============================== 84 85* ``zephyr,memory-region-mpu`` was renamed ``zephyr,memory-attr`` and its type 86 moved from 'enum' to 'int'. To have a seamless conversion this is the 87 required change in the DT: 88 89 .. code-block:: none 90 91 - "RAM" -> <( DT_MEM_ARM(ATTR_MPU_RAM) )> 92 - "RAM_NOCACHE" -> <( DT_MEM_ARM(ATTR_MPU_RAM_NOCACHE) )> 93 - "FLASH" -> <( DT_MEM_ARM(ATTR_MPU_FLASH) )> 94 - "PPB" -> <( DT_MEM_ARM(ATTR_MPU_PPB) )> 95 - "IO" -> <( DT_MEM_ARM(ATTR_MPU_IO) )> 96 - "EXTMEM" -> <( DT_MEM_ARM(ATTR_MPU_EXTMEM) )> 97 98* Device dependencies (incorrectly referred as "device handles" in some areas) 99 are now an optional feature enabled by :kconfig:option:`CONFIG_DEVICE_DEPS`. 100 This means that an extra linker stage is no longer necessary if this option is 101 not enabled. 102 103* On all STM32 ADC, it is no longer possible to read sensor channels (Vref, 104 Vbat or temperature) using the ADC driver. The dedicated sensor driver should 105 be used instead. This change is due to a limitation on STM32F4 where the 106 channels for temperature and Vbat are identical, and the impossibility of 107 determining what we want to measure using solely the ADC API. 108 109* The RAM disk driver has been changed to support multiple instances and instantiation 110 using devicetree. As a result, Kconfig option :kconfig:option:`CONFIG_DISK_RAM_VOLUME_SIZE` 111 and Kconfig option :kconfig:option:`CONFIG_DISK_RAM_VOLUME_NAME` are removed, 112 and the application using the RAM disk must instantiate it using devicetree, 113 as in the following example: 114 115 .. code-block:: devicetree 116 117 / { 118 ramdisk0 { 119 compatible = "zephyr,ram-disk"; 120 disk-name = "RAM"; 121 sector-size = <512>; 122 sector-count = <192>; 123 }; 124 }; 125 126* The :dtcompatible:`goodix,gt911`, :dtcompatible:`xptek,xpt2046` and 127 :dtcompatible:`hynitron,cst816s` drivers have been converted from Kscan to 128 Input, they can still be used with Kscan applications by adding a 129 :dtcompatible:`zephyr,kscan-input` node. 130 131* The ``zephyr,gpio-keys`` binding has been merged into 132 :dtcompatible:`gpio-keys` and the callback definition has been renamed from 133 ``INPUT_LISTENER_CB_DEFINE`` to :c:macro:`INPUT_CALLBACK_DEFINE`. 134 135* The :dtcompatible:`ti,bq274xx` driver was using incorrect units for capacity 136 and power channels, these have been fixed and scaled by x1000 factor from the 137 previous implementation, any application using them has to be changed 138 accordingly. 139 140* The configuration options for the SSD1306 display driver can now be provided 141 via the Devicetree binding :dtcompatible:`solomon,ssd1306fb`. The following 142 Kconfig options: ``CONFIG_SSD1306_DEFAULT``, 143 ``CONFIG_SSD1306_SH1106_COMPATIBLE``, and ``CONFIG_SSD1306_REVERSE_MODE`` have 144 been removed. 145 146 * You can remove ``CONFIG_SSD1306_DEFAULT`` without any other modification. 147 148 * ``CONFIG_SSD1306_SH1106_COMPATIBLE`` was used to assert that the device is 149 (compatible with) SH1106. This has been replaced by a dedicated dts 150 compatible declaration. You may update an existing sh1106 node to change the 151 ``compatible`` designation from :dtcompatible:`solomon,ssd1306fb` to 152 :dtcompatible:`sinowealth,sh1106`. 153 154 * ``CONFIG_SSD1306_REVERSE_MODE`` is now set using the ``inversion-on`` 155 property of the devicetree node. 156 157* GPIO drivers not implementing IRQ related operations must now provide 158 ``NULL`` to the relevant operations: ``pin_interrupt_configure``, 159 ``manage_callback``, ``get_pending_int``. The public API will return 160 ``-ENOSYS`` when these are not available, instead of ``-ENOTSUP``. 161 162* STM32 Ethernet driver was misusing :c:func:`hwinfo_get_device_id` to generate 163 last 3 bytes of mac address, resulting in a high risk of collision when using 164 SoCs from the same lot. This is now fixed to use the whole range of entropy 165 available from the unique ID (96 bits). Devices using unique ID based mac address 166 will see last 3 bytes of their MAC address modified by this change. 167 168* On all STM32 (except F1x and F37x series), two new required properties have been 169 added to ADC to configure the source clock and the prescaler. 170 ``st,adc-clock-source`` allows choosing either synchronous or asynchronous clock source. 171 ``st,adc-prescaler`` allows setting the value of the prescaler for the chosen clock source. 172 Not all combinations are allowed. Refer to the appropriate RefMan for more information. 173 When choosing asynchronous clock, the choice of the kernel source clock is made in the 174 ``clocks`` node as it is done for other peripherals, for example, to select 175 HSI16 as clock source for STM32G0: 176 177 .. code-block:: devicetree 178 179 &adc { 180 clocks = <&rcc STM32_CLOCK_BUS_APB1_2 0x00100000>, 181 <&rcc STM32_SRC_HSI ADC_SEL(2)>; 182 }; 183 184* On NXP boards with LPC DMA, the DMA controller node used to have its ``dma-channels`` property 185 set in the board DTS as a way to configure the amount of structures the driver will allocate. 186 This did not match the zephyr dma-controller binding, so this property is now fixed and set 187 in the SOC devicetree definition. Downstream boards should not override this property and 188 instead use the new driver Kconfig 189 :kconfig:option:`CONFIG_DMA_MCUX_LPC_NUMBER_OF_CHANNELS_ALLOCATED`. 190 191* The LPC55XXX series SOC (except LPC55S06) default main clock has been 192 updated to PLL1 source from XTAL32K running at 144MHZ. If the new 193 kconfig option :kconfig:option:`CONFIG_INIT_PLL1` 194 is disabled then the main clock is muxed to FRO_HR as before. 195 196* The Kconfig option ``CONFIG_GPIO_NCT38XX_INTERRUPT`` has been renamed to 197 :kconfig:option:`CONFIG_GPIO_NCT38XX_ALERT`. 198 199* The CAN controller timing API functions :c:func:`can_set_timing` and :c:func:`can_set_timing_data` 200 no longer fallback to the (Re-)Synchronization Jump Width (SJW) value set in the devicetree 201 properties for the given CAN controller upon encountering an SJW value corresponding to 202 ``CAN_SJW_NO_CHANGE`` (which is no longer available). The caller will therefore need to fill in 203 the ``sjw`` field in :c:struct:`can_timing`. To aid in this, the :c:func:`can_calc_timing` and 204 :c:func:`can_calc_timing_data` functions now automatically calculate a suitable SJW. The 205 calculated SJW can be overwritten by the caller if needed. The CAN controller API functions 206 :c:func:`can_set_bitrate` and :c:func:`can_set_bitrate_data` now also automatically calculate a 207 suitable SJW, but their SJW cannot be overwritten by the caller. 208 209* The CAN ISO-TP message configuration in :c:struct:`isotp_msg_id` is changed to use the following 210 flags instead of bit fields: 211 212 * :c:macro:`ISOTP_MSG_EXT_ADDR` to enable ISO-TP extended addressing 213 * :c:macro:`ISOTP_MSG_FIXED_ADDR` to enable ISO-TP fixed addressing 214 * :c:macro:`ISOTP_MSG_IDE` to use extended (29-bit) CAN IDs 215 216 The two new flags :c:macro:`ISOTP_MSG_FDF` and :c:macro:`ISOTP_MSG_BRS` were added for CAN FD 217 mode. 218 219* NXP i.MX RT based boards should now enable 220 :kconfig:option:`CONFIG_DEVICE_CONFIGURATION_DATA` at the board level when 221 using a DCD with the RT bootrom, and enable 222 :kconfig:option:`CONFIG_NXP_IMX_EXTERNAL_SDRAM` when using external SDRAM 223 via the SEMC 224 225* NXP i.MX RT11xx series SNVS pin control name identifiers have been updated to 226 match with the source data for these SOCs. The pin names have had the 227 suffix ``dig`` added. For example, ``iomuxc_snvs_wakeup_gpio13_io00`` has 228 been renamed to ``iomuxc_snvs_wakeup_dig_gpio13_io00`` 229 230Power Management 231================ 232 233* Platforms that implement power management hooks must explicitly select 234 :kconfig:option:`CONFIG_HAS_PM` in Kconfig. This is now a dependency of 235 :kconfig:option:`CONFIG_PM`. Before this change all platforms could enable 236 :kconfig:option:`CONFIG_PM` because empty weak stubs were provided, however, 237 this is no longer supported. As a result of this change, power management 238 hooks are no longer defined as weaks. 239 240* Multiple platforms no longer support powering the system off using 241 :c:func:`pm_state_force`. The new :c:func:`sys_poweroff` API must be used. 242 Migrated platforms include Nordic nRF, STM32, ESP32 and TI CC13XX/26XX. The 243 new API is independent from :kconfig:option:`CONFIG_PM`. It requires 244 :kconfig:option:`CONFIG_POWEROFF` to be enabled, which depends on 245 :kconfig:option:`CONFIG_HAS_POWEROFF`, an option selected by platforms 246 implementing the required new hooks. 247 248Bootloader 249========== 250 251* The :kconfig:option:`CONFIG_BOOTLOADER_SRAM_SIZE` default value is now ``0`` (was 252 ``16``). Bootloaders that use a part of the SRAM should set this value to an 253 appropriate size. :github:`60371` 254 255Bluetooth 256========= 257 258* The ``accept()`` callback's signature in :c:struct:`bt_l2cap_server` has 259 changed to ``int (*accept)(struct bt_conn *conn, struct bt_l2cap_server 260 *server, struct bt_l2cap_chan **chan)``, 261 adding a new ``server`` parameter pointing to the :c:struct:`bt_l2cap_server` 262 structure instance the callback relates to. :github:`60536` 263 264Networking 265========== 266 267* A new networking Kconfig option :kconfig:option:`CONFIG_NET_INTERFACE_NAME` 268 defaults to ``y``. The option allows user to set a name to a network interface. 269 During system startup a default name is assigned to the network interface like 270 ``eth0`` to the first Ethernet network interface. The option affects the behavior 271 of ``SO_BINDTODEVICE`` BSD socket option. If the Kconfig option is set to ``n``, 272 which is how the system worked earlier, then the name of the device assigned 273 to the network interface is used by the ``SO_BINDTODEVICE`` socket option. 274 If the Kconfig option is set to ``y`` (current default), then the network 275 interface name is used by the ``SO_BINDTODEVICE`` socket option. 276 277* Ethernet PHY devicetree bindings were updated to use the standard ``reg`` 278 property for the PHY address instead of a custom ``address`` property. As a 279 result, MDIO controller nodes now require ``#address-cells`` and 280 ``#size-cells`` properties. Similarly, Ethernet PHY devicetree nodes and 281 corresponding driver were updated to consistently use the node name 282 ``ethernet-phy`` instead of ``phy``. Devicetrees and overlays must be updated 283 accordingly: 284 285 .. code-block:: devicetree 286 287 mdio { 288 compatible = "mdio-controller"; 289 #address-cells = <1>; 290 #size-cells = <0>; 291 292 ethernet-phy@0 { 293 compatible = "ethernet-phy"; 294 reg = <0>; 295 }; 296 }; 297 298Other Subsystems 299================ 300 301* ZBus runtime observers implementation now relies on the HEAP memory instead of a memory slab. 302 Thus, zbus' configuration (kconfig) related to runtime observers has changed. To keep your runtime 303 observers code working correctly, you need to: 304 305 - Replace the integer ``CONFIG_ZBUS_RUNTIME_OBSERVERS_POOL_SIZE`` with the boolean 306 :kconfig:option:`CONFIG_ZBUS_RUNTIME_OBSERVERS`; 307 - Set the HEAP size with the :kconfig:option:`CONFIG_HEAP_MEM_POOL_SIZE`. 308 309* The zbus VDED delivery sequence has changed. Check the :ref:`documentation<zbus delivery 310 sequence>` to verify if it will affect your code. 311 312* MCUmgr SMP version 2 error codes entry has changed due to a collision with an 313 existing response in shell_mgmt. Previously, these errors had the entry ``ret`` 314 but now have the entry ``err``. ``smp_add_cmd_ret()`` is now deprecated and 315 :c:func:`smp_add_cmd_err` should be used instead, ``MGMT_CB_ERROR_RET`` is 316 now deprecated and :c:enumerator:`MGMT_CB_ERROR_ERR` should be used instead. 317 SMP version 2 error code defines for in-tree modules have been updated to 318 replace the ``*_RET_RC_*`` parts with ``*_ERR_*``. 319 320* MCUmgr SMP version 2 error translation (to legacy MCUmgr error code) is now 321 handled in function handlers by setting the ``mg_translate_error`` function 322 pointer of :c:struct:`mgmt_group` when registering a group. See 323 :c:type:`smp_translate_error_fn` for function details. Any SMP version 2 324 handlers made for Zephyr 3.4 need to be updated to include these translation 325 functions when the groups are registered. 326 327ARM 328=== 329 330* ARM SoC initialization routines no longer need to call `NMI_INIT()`. The 331 macro call has been removed as it was not doing anything useful. 332 333RISC V 334====== 335 336* The :kconfig:option:`CONFIG_RISCV_MTVEC_VECTORED_MODE` Kconfig option was renamed to 337 :kconfig:option:`CONFIG_RISCV_VECTORED_MODE`. 338 339Recommended Changes 340******************* 341 342* Setting the GIC architecture version by selecting 343 :kconfig:option:`CONFIG_GIC_V1`, :kconfig:option:`CONFIG_GIC_V2` and 344 :kconfig:option:`CONFIG_GIC_V3` directly in Kconfig has been deprecated. 345 The GIC version should now be specified by adding the appropriate compatible, for 346 example :dtcompatible:`arm,gic-v2`, to the GIC node in the device tree. 347 348* Nordic nRF based boards using :kconfig:option:`CONFIG_NFCT_PINS_AS_GPIOS` 349 to configure NFCT pins as GPIOs, should instead set the new UICR 350 ``nfct-pins-as-gpios`` property in devicetree. It can be set like this in the 351 board devicetree files: 352 353 .. code-block:: devicetree 354 355 &uicr { 356 nfct-pins-as-gpios; 357 }; 358 359* Nordic nRF based boards using :kconfig:option:`CONFIG_GPIO_AS_PINRESET` 360 to configure reset GPIO as nRESET, should instead set the new UICR 361 ``gpio-as-nreset`` property in devicetree. It can be set like this in the 362 board devicetree files: 363 364 .. code-block:: devicetree 365 366 &uicr { 367 gpio-as-nreset; 368 }; 369 370* The :kconfig:option:`CONFIG_MODEM_GSM_PPP` modem driver is obsolete. 371 Instead the new :kconfig:option:`CONFIG_MODEM_CELLULAR` driver should be used. 372 As part of this :kconfig:option:`CONFIG_GSM_MUX` and :kconfig:option:`CONFIG_UART_MUX` are being 373 marked as deprecated as well. The new modem subsystem :kconfig:option:`CONFIG_MODEM_CMUX` 374 and :kconfig:option:`CONFIG_MODEM_PPP` should be used instead. 375 376* Device drivers should now be restricted to ``PRE_KERNEL_1``, ``PRE_KERNEL_2`` 377 and ``POST_KERNEL`` initialization levels. Other device initialization levels, 378 including ``EARLY``, ``APPLICATION``, and ``SMP``, have been deprecated and 379 will be removed in future releases. Note that these changes do not apply to 380 initialization levels used in the context of the ``init.h`` API, 381 e.g. :c:macro:`SYS_INIT`. 382 383* The following CAN controller devicetree properties are now deprecated in favor specifying the 384 initial CAN bitrate using the ``bus-speed``, ``sample-point``, ``bus-speed-data``, and 385 ``sample-point-data`` properties: 386 387 * ``sjw`` 388 * ``prop-seg`` 389 * ``phase-seg1`` 390 * ``phase-seg1`` 391 * ``sjw-data`` 392 * ``prop-seg-data`` 393 * ``phase-seg1-data`` 394 * ``phase-seg1-data`` 395 396* ``<zephyr/arch/arm/aarch32/cortex_a_r/cmsis.h>`` and 397 ``<zephyr/arch/arm/aarch32/cortex_m/cmsis.h>`` are now deprecated in favor of 398 including ``<cmsis_core.h>`` instead. The new header is part of the CMSIS glue 399 code in the ``modules`` directory. 400 401* Random API header ``<zephyr/random/rand32.h>`` is deprecated in favor of 402 ``<zephyr/random/random.h>``. The old header will be removed in future releases 403 and its usage should be avoided. 404
