f51c8ee739
Utilize a code spell-checking tool to scan for and correct spelling errors in all files within the doc/releases directory. The typo in the 'Issue Related Items' section will be left unchanged. Signed-off-by: Pisit Sawangvonganan <pisit@ndrsolution.com>
433 lines
19 KiB
ReStructuredText
433 lines
19 KiB
ReStructuredText
: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.
|