You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
432 lines
19 KiB
432 lines
19 KiB
:orphan: |
|
|
|
.. _migration_3.5: |
|
|
|
Migration guide to Zephyr v3.5.0 |
|
################################ |
|
|
|
This document describes the changes required or recommended when migrating your |
|
application from Zephyr v3.4.0 to Zephyr v3.5.0. |
|
|
|
Any other changes (not directly related to migrating applications) can be found in |
|
the :ref:`release notes<zephyr_3.5>`. |
|
|
|
Required changes |
|
**************** |
|
|
|
Kernel |
|
====== |
|
|
|
* The kernel :c:func:`k_mem_slab_free` function has changed its signature, now |
|
taking a ``void *mem`` pointer instead of a ``void **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 with :kconfig:option:`CONFIG_ASSERT`, will |
|
detect if you pass the function memory not belonging to the memory blocks in |
|
the slab. |
|
|
|
* :c:macro:`CONTAINER_OF` now performs type checking, this was very commonly |
|
misused to obtain user structure from :c:struct:`k_work` pointers without |
|
passing from :c:struct:`k_work_delayable`. This would now result in a build |
|
error and have to be done correctly using |
|
:c:func:`k_work_delayable_from_work`. |
|
|
|
C Library |
|
========= |
|
|
|
* 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 |
|
(:kconfig:option:`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 |
|
:kconfig:option:`CONFIG_MMU` or :kconfig:option:`ARCH_POSIX`, 2kB with |
|
:kconfig:option:`CONFIG_USERSPACE` and |
|
:kconfig:option:`CONFIG_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 adjusting |
|
:kconfig:option:`CONFIG_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 has four different printf/scanf variants supported in Zephyr, |
|
'double', 'long long', 'integer', and 'minimal. 'double' offers a |
|
complete printf implementation with exact floating point in decimal and |
|
hexadecimal formats, full integer support including long long, C99 |
|
integer size specifiers (j, z, t) and POSIX positional arguments. 'long |
|
long' mode removes float support, 'integer' removes long long support |
|
while 'minimal' mode also removes support for format modifiers and |
|
positional arguments. Building the library as a module allows finer |
|
control over the feature set provided at each level. |
|
|
|
* 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 |
|
:kconfig:option:`CONFIG_CBPRINTF_FP_SUPPORT`, you will see increased |
|
memory usage unless you also disable |
|
:kconfig:option:`CONFIG_PICOLIBC_IO_FLOAT_EXACT`, which switches Picolibc |
|
to a smaller, but inexact conversion algorithm. This requires building |
|
Picolibc as a module. |
|
|
|
Optional Modules |
|
================ |
|
|
|
The following modules have been made optional and are not downloaded with `west update` by default anymore: |
|
|
|
* ``chre`` |
|
* ``lz4`` |
|
* ``nanopb`` |
|
* ``psa-arch-tests`` |
|
* ``sof`` |
|
* ``tf-m-tests`` |
|
* ``tflite-micro`` |
|
* ``thrift`` |
|
* ``zscilib`` |
|
|
|
To enable them again use the ``west config manifest.project-filter -- +<module |
|
name>`` command, or ``west config manifest.group-filter -- +optional`` to |
|
enable all optional modules, and then run ``west update`` again. |
|
|
|
Device Drivers and Device Tree |
|
============================== |
|
|
|
* ``zephyr,memory-region-mpu`` was renamed ``zephyr,memory-attr`` and its type |
|
moved from 'enum' to 'int'. To have a seamless conversion this is the |
|
required change in the DT: |
|
|
|
.. code-block:: none |
|
|
|
- "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) )> |
|
|
|
* Device dependencies (incorrectly referred as "device handles" in some areas) |
|
are now an optional feature enabled by :kconfig:option:`CONFIG_DEVICE_DEPS`. |
|
This means that an extra linker stage is no longer necessary if this option is |
|
not enabled. |
|
|
|
* 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 RAM disk driver has been changed to support multiple instances and instantiation |
|
using devicetree. As a result, Kconfig option :kconfig:option:`CONFIG_DISK_RAM_VOLUME_SIZE` |
|
and Kconfig option :kconfig:option:`CONFIG_DISK_RAM_VOLUME_NAME` are removed, |
|
and the application using the RAM disk must instantiate it using devicetree, |
|
as in the following example: |
|
|
|
.. code-block:: devicetree |
|
|
|
/ { |
|
ramdisk0 { |
|
compatible = "zephyr,ram-disk"; |
|
disk-name = "RAM"; |
|
sector-size = <512>; |
|
sector-count = <192>; |
|
}; |
|
}; |
|
|
|
* The :dtcompatible:`goodix,gt911`, :dtcompatible:`xptek,xpt2046` and |
|
:dtcompatible:`hynitron,cst816s` drivers have been converted from Kscan to |
|
Input, they can still be used with Kscan applications by adding a |
|
:dtcompatible:`zephyr,kscan-input` node. |
|
|
|
* The ``zephyr,gpio-keys`` binding has been merged into |
|
:dtcompatible:`gpio-keys` and the callback definition has been renamed from |
|
``INPUT_LISTENER_CB_DEFINE`` to :c:macro:`INPUT_CALLBACK_DEFINE`. |
|
|
|
* The :dtcompatible:`ti,bq274xx` driver was using incorrect units for capacity |
|
and power channels, these have been fixed and scaled by x1000 factor from the |
|
previous implementation, any application using them has to be changed |
|
accordingly. |
|
|
|
* The configuration options for the SSD1306 display driver can now be provided |
|
via the Devicetree binding :dtcompatible:`solomon,ssd1306fb`. The following |
|
Kconfig options: ``CONFIG_SSD1306_DEFAULT``, |
|
``CONFIG_SSD1306_SH1106_COMPATIBLE``, and ``CONFIG_SSD1306_REVERSE_MODE`` have |
|
been removed. |
|
|
|
* You can remove ``CONFIG_SSD1306_DEFAULT`` without any other modification. |
|
|
|
* ``CONFIG_SSD1306_SH1106_COMPATIBLE`` was used to assert that the device is |
|
(compatible with) SH1106. This has been replaced by a dedicated dts |
|
compatible declaration. You may update an existing sh1106 node to change the |
|
``compatible`` designation from :dtcompatible:`solomon,ssd1306fb` to |
|
:dtcompatible:`sinowealth,sh1106`. |
|
|
|
* ``CONFIG_SSD1306_REVERSE_MODE`` is now set using the ``inversion-on`` |
|
property of the devicetree node. |
|
|
|
* GPIO drivers not implementing IRQ related operations must now provide |
|
``NULL`` to the relevant operations: ``pin_interrupt_configure``, |
|
``manage_callback``, ``get_pending_int``. The public API will return |
|
``-ENOSYS`` when these are not available, instead of ``-ENOTSUP``. |
|
|
|
* STM32 Ethernet driver was misusing :c:func:`hwinfo_get_device_id` to generate |
|
last 3 bytes of mac address, resulting in a high risk of collision when using |
|
SoCs from the same lot. This is now fixed to use the whole range of entropy |
|
available from the unique ID (96 bits). Devices using unique ID based mac address |
|
will see last 3 bytes of their MAC address modified by this change. |
|
|
|
* On all STM32 (except F1x and F37x series), two new required properties have been |
|
added to ADC to configure the source clock and the prescaler. |
|
``st,adc-clock-source`` allows choosing either synchronous or asynchronous clock source. |
|
``st,adc-prescaler`` allows setting the value of the prescaler for the chosen clock source. |
|
Not all combinations are allowed. Refer to the appropriate RefMan for more information. |
|
When choosing asynchronous clock, the choice of the kernel source clock is made in the |
|
``clocks`` node as it is done for other peripherals, for example, to select |
|
HSI16 as clock source for STM32G0: |
|
|
|
.. code-block:: devicetree |
|
|
|
&adc { |
|
clocks = <&rcc STM32_CLOCK_BUS_APB1_2 0x00100000>, |
|
<&rcc STM32_SRC_HSI ADC_SEL(2)>; |
|
}; |
|
|
|
* On NXP boards with LPC DMA, the DMA controller node used to have its ``dma-channels`` property |
|
set in the board DTS as a way to configure the amount of structures the driver will allocate. |
|
This did not match the zephyr dma-controller binding, so this property is now fixed and set |
|
in the SOC devicetree definition. Downstream boards should not override this property and |
|
instead use the new driver Kconfig |
|
:kconfig:option:`CONFIG_DMA_MCUX_LPC_NUMBER_OF_CHANNELS_ALLOCATED`. |
|
|
|
* The LPC55XXX series SOC (except LPC55S06) default main clock has been |
|
updated to PLL1 source from XTAL32K running at 144MHZ. If the new |
|
kconfig option :kconfig:option:`CONFIG_INIT_PLL1` |
|
is disabled then the main clock is muxed to FRO_HR as before. |
|
|
|
* The Kconfig option ``CONFIG_GPIO_NCT38XX_INTERRUPT`` has been renamed to |
|
:kconfig:option:`CONFIG_GPIO_NCT38XX_ALERT`. |
|
|
|
* The CAN controller timing API functions :c:func:`can_set_timing` and :c:func:`can_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 to |
|
``CAN_SJW_NO_CHANGE`` (which is no longer available). The caller will therefore need to fill in |
|
the ``sjw`` field in :c:struct:`can_timing`. To aid in this, the :c:func:`can_calc_timing` and |
|
:c:func:`can_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 functions |
|
:c:func:`can_set_bitrate` and :c:func:`can_set_bitrate_data` now also automatically calculate a |
|
suitable SJW, but their SJW cannot be overwritten by the caller. |
|
|
|
* The CAN ISO-TP message configuration in :c:struct:`isotp_msg_id` is changed to use the following |
|
flags instead of bit fields: |
|
|
|
* :c:macro:`ISOTP_MSG_EXT_ADDR` to enable ISO-TP extended addressing |
|
* :c:macro:`ISOTP_MSG_FIXED_ADDR` to enable ISO-TP fixed addressing |
|
* :c:macro:`ISOTP_MSG_IDE` to use extended (29-bit) CAN IDs |
|
|
|
The two new flags :c:macro:`ISOTP_MSG_FDF` and :c:macro:`ISOTP_MSG_BRS` were added for CAN FD |
|
mode. |
|
|
|
* NXP i.MX RT based boards should now enable |
|
:kconfig:option:`CONFIG_DEVICE_CONFIGURATION_DATA` at the board level when |
|
using a DCD with the RT bootrom, and enable |
|
:kconfig:option:`CONFIG_NXP_IMX_EXTERNAL_SDRAM` when using external SDRAM |
|
via the SEMC |
|
|
|
* NXP i.MX RT11xx series SNVS pin control name identifiers have been updated to |
|
match with the source data for these SOCs. The pin names have had the |
|
suffix ``dig`` added. For example, ``iomuxc_snvs_wakeup_gpio13_io00`` has |
|
been renamed to ``iomuxc_snvs_wakeup_dig_gpio13_io00`` |
|
|
|
Power Management |
|
================ |
|
|
|
* Platforms that implement power management hooks must explicitly select |
|
:kconfig:option:`CONFIG_HAS_PM` in Kconfig. This is now a dependency of |
|
:kconfig:option:`CONFIG_PM`. Before this change all platforms could enable |
|
:kconfig:option:`CONFIG_PM` because empty weak stubs were provided, however, |
|
this is no longer supported. As a result of this change, power management |
|
hooks are no longer defined as weaks. |
|
|
|
* Multiple platforms no longer support powering the system off using |
|
:c:func:`pm_state_force`. The new :c:func:`sys_poweroff` API must be used. |
|
Migrated platforms include Nordic nRF, STM32, ESP32 and TI CC13XX/26XX. The |
|
new API is independent from :kconfig:option:`CONFIG_PM`. It requires |
|
:kconfig:option:`CONFIG_POWEROFF` to be enabled, which depends on |
|
:kconfig:option:`CONFIG_HAS_POWEROFF`, an option selected by platforms |
|
implementing the required new hooks. |
|
|
|
Bootloader |
|
========== |
|
|
|
* The :kconfig:option:`CONFIG_BOOTLOADER_SRAM_SIZE` default value is now ``0`` (was |
|
``16``). Bootloaders that use a part of the SRAM should set this value to an |
|
appropriate size. :github:`60371` |
|
|
|
Bluetooth |
|
========= |
|
|
|
* The ``accept()`` callback's signature in :c:struct:`bt_l2cap_server` has |
|
changed to ``int (*accept)(struct bt_conn *conn, struct bt_l2cap_server |
|
*server, struct bt_l2cap_chan **chan)``, |
|
adding a new ``server`` parameter pointing to the :c:struct:`bt_l2cap_server` |
|
structure instance the callback relates to. :github:`60536` |
|
|
|
Networking |
|
========== |
|
|
|
* A new networking Kconfig option :kconfig:option:`CONFIG_NET_INTERFACE_NAME` |
|
defaults to ``y``. The option allows user to set a name to a network interface. |
|
During system startup a default name is assigned to the network interface like |
|
``eth0`` to the first Ethernet network interface. The option affects the behavior |
|
of ``SO_BINDTODEVICE`` BSD socket option. If the Kconfig option is set to ``n``, |
|
which is how the system worked earlier, then the name of the device assigned |
|
to the network interface is used by the ``SO_BINDTODEVICE`` socket option. |
|
If the Kconfig option is set to ``y`` (current default), then the network |
|
interface name is used by the ``SO_BINDTODEVICE`` socket option. |
|
|
|
* Ethernet PHY devicetree bindings were updated to use the standard ``reg`` |
|
property for the PHY address instead of a custom ``address`` 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 name |
|
``ethernet-phy`` instead of ``phy``. Devicetrees and overlays must be updated |
|
accordingly: |
|
|
|
.. code-block:: devicetree |
|
|
|
mdio { |
|
compatible = "mdio-controller"; |
|
#address-cells = <1>; |
|
#size-cells = <0>; |
|
|
|
ethernet-phy@0 { |
|
compatible = "ethernet-phy"; |
|
reg = <0>; |
|
}; |
|
}; |
|
|
|
Other Subsystems |
|
================ |
|
|
|
* ZBus runtime observers implementation now relies on the HEAP memory instead of a memory slab. |
|
Thus, zbus' configuration (kconfig) related to runtime observers has changed. To keep your runtime |
|
observers code working correctly, you need to: |
|
|
|
- Replace the integer ``CONFIG_ZBUS_RUNTIME_OBSERVERS_POOL_SIZE`` with the boolean |
|
:kconfig:option:`CONFIG_ZBUS_RUNTIME_OBSERVERS`; |
|
- Set the HEAP size with the :kconfig:option:`CONFIG_HEAP_MEM_POOL_SIZE`. |
|
|
|
* The zbus VDED delivery sequence has changed. Check the :ref:`documentation<zbus delivery |
|
sequence>` to verify if it will affect your code. |
|
|
|
* 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 entry ``err``. ``smp_add_cmd_ret()`` is now deprecated and |
|
:c:func:`smp_add_cmd_err` should be used instead, ``MGMT_CB_ERROR_RET`` is |
|
now deprecated and :c:enumerator:`MGMT_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 of :c:struct:`mgmt_group` when registering a group. See |
|
:c:type:`smp_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. |
|
|
|
ARM |
|
=== |
|
|
|
* ARM SoC initialization routines no longer need to call `NMI_INIT()`. The |
|
macro call has been removed as it was not doing anything useful. |
|
|
|
RISC V |
|
====== |
|
|
|
* The :kconfig:option:`CONFIG_RISCV_MTVEC_VECTORED_MODE` Kconfig option was renamed to |
|
:kconfig:option:`CONFIG_RISCV_VECTORED_MODE`. |
|
|
|
Recommended Changes |
|
******************* |
|
|
|
* Setting the GIC architecture version by selecting |
|
:kconfig:option:`CONFIG_GIC_V1`, :kconfig:option:`CONFIG_GIC_V2` and |
|
:kconfig:option:`CONFIG_GIC_V3` directly in Kconfig has been deprecated. |
|
The GIC version should now be specified by adding the appropriate compatible, for |
|
example :dtcompatible:`arm,gic-v2`, to the GIC node in the device tree. |
|
|
|
* Nordic nRF based boards using :kconfig:option:`CONFIG_NFCT_PINS_AS_GPIOS` |
|
to configure NFCT pins as GPIOs, should instead set the new UICR |
|
``nfct-pins-as-gpios`` property in devicetree. It can be set like this in the |
|
board devicetree files: |
|
|
|
.. code-block:: devicetree |
|
|
|
&uicr { |
|
nfct-pins-as-gpios; |
|
}; |
|
|
|
* Nordic nRF based boards using :kconfig:option:`CONFIG_GPIO_AS_PINRESET` |
|
to configure reset GPIO as nRESET, should instead set the new UICR |
|
``gpio-as-nreset`` property in devicetree. It can be set like this in the |
|
board devicetree files: |
|
|
|
.. code-block:: devicetree |
|
|
|
&uicr { |
|
gpio-as-nreset; |
|
}; |
|
|
|
* The :kconfig:option:`CONFIG_MODEM_GSM_PPP` modem driver is obsolete. |
|
Instead the new :kconfig:option:`CONFIG_MODEM_CELLULAR` driver should be used. |
|
As part of this :kconfig:option:`CONFIG_GSM_MUX` and :kconfig:option:`CONFIG_UART_MUX` are being |
|
marked as deprecated as well. The new modem subsystem :kconfig:option:`CONFIG_MODEM_CMUX` |
|
and :kconfig:option:`CONFIG_MODEM_PPP` should be used instead. |
|
|
|
* Device drivers should now be restricted to ``PRE_KERNEL_1``, ``PRE_KERNEL_2`` |
|
and ``POST_KERNEL`` initialization levels. Other device initialization levels, |
|
including ``EARLY``, ``APPLICATION``, and ``SMP``, 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 the ``init.h`` API, |
|
e.g. :c:macro:`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``, and |
|
``sample-point-data`` properties: |
|
|
|
* ``sjw`` |
|
* ``prop-seg`` |
|
* ``phase-seg1`` |
|
* ``phase-seg1`` |
|
* ``sjw-data`` |
|
* ``prop-seg-data`` |
|
* ``phase-seg1-data`` |
|
* ``phase-seg1-data`` |
|
|
|
* ``<zephyr/arch/arm/aarch32/cortex_a_r/cmsis.h>`` and |
|
``<zephyr/arch/arm/aarch32/cortex_m/cmsis.h>`` are now deprecated in favor of |
|
including ``<cmsis_core.h>`` instead. The new header is part of the CMSIS glue |
|
code in the ``modules`` directory. |
|
|
|
* Random API header ``<zephyr/random/rand32.h>`` is deprecated in favor of |
|
``<zephyr/random/random.h>``. The old header will be removed in future releases |
|
and its usage should be avoided.
|
|
|