Skip to content

Latest commit

 

History

History
719 lines (570 loc) · 31.1 KB

migration-guide-3.6.rst

File metadata and controls

719 lines (570 loc) · 31.1 KB
orphan:

Migration guide to Zephyr v3.6.0

This document describes the changes required when migrating your application from Zephyr v3.5.0 to Zephyr v3.6.0.

Any other changes (not directly related to migrating applications) can be found in the :ref:`release notes<zephyr_3.6>`.

Build System

  • The deprecated prj_<board>.conf Kconfig file support has been removed, projects that use this should switch to using board Kconfig fragments instead (boards/<board>.conf).
  • Until now _POSIX_C_SOURCE, _XOPEN_SOURCE, and _XOPEN_SOURCE_EXTENDED were defined globally when building for the native (ARCH_POSIX) targets, and _POSIX_C_SOURCE when building with PicolibC. Since this release, these are set only for the files that need them. If your library or application needed this, you may start getting an "implicit declaration" warning for functions whose prototypes are only exposed if one of these is defined. If so, you can fix it by defining the corresponding macro in your C source file before any include, or by adding the equivalent of target_compile_definitions(app PRIVATE _POSIX_C_SOURCE=200809L) to your application or zephyr_library_compile_definitions(_POSIX_C_SOURCE=200809L) to your library.
  • Build type by setting CONF_FILE to prj_<build>.conf is now deprecated, users should instead use the new -DFILE_SUFFIX feature :ref:`application-file-suffixes`.

Kernel

  • The system heap size and its availability is now determined by a K_HEAP_MEM_POOL_SIZE define instead of the :kconfig:option:`CONFIG_HEAP_MEM_POOL_SIZE` Kconfig option. Subsystems can specify their own custom system heap size requirements by specifying Kconfig options with the prefix CONFIG_HEAP_MEM_POOL_ADD_SIZE_. The old Kconfig option still exists, but will be overridden if the custom requirements are larger. To force the old Kconfig option to be used, even when its value is less than the indicated custom requirements, a new :kconfig:option:`CONFIG_HEAP_MEM_POOL_IGNORE_MIN` option has been introduced (which defaults being disabled).

Boards

  • The deprecated Nordic SoC Kconfig option NRF_STORE_REBOOT_TYPE_GPREGRET has been removed, applications that use this should switch to using the :ref:`boot_mode_api` instead.
  • NXP: Enabled :ref:`linkserver<linkserver-debug-host-tools>` to be the default runner on the following NXP boards: mimxrt685_evk_cm33, frdm_k64f, mimxrt1050_evk, frdm_kl25z, mimxrt1020_evk, mimxrt1015_evk

Modules

Optional Modules

The following modules have been made optional and are not downloaded with west update by default anymore:

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.

MCUboot

  • MCUboot's deprecated CONFIG_ZEPHYR_TRY_MASS_ERASE Kconfig option has been removed. If an erase is needed when flashing MCUboot, this should now be provided directly to the west command e.g. west flash --erase. (:github:`64703`)

zcbor

Device Drivers and Devicetree

Devicetree Labels

  • Various deprecated macros related to the deprecated devicetree label property were removed. These are listed in the following table. The table also provides replacements.

    However, if you are still using code like device_get_binding(DT_LABEL(node_id)), consider replacing it with something like DEVICE_DT_GET(node_id) instead. The DEVICE_DT_GET() macro avoids run-time string comparisons, and is also safer because it will fail the build if the device does not exist.

    Removed macro

    Replacement

    DT_GPIO_LABEL(node_id, gpio_pha)

    DT_PROP(DT_GPIO_CTLR(node_id, gpio_pha), label)

    DT_GPIO_LABEL_BY_IDX(node_id, gpio_pha, idx)

    DT_PROP(DT_GPIO_CTLR_BY_IDX(node_id, gpio_pha, idx), label)

    DT_INST_GPIO_LABEL(inst, gpio_pha)

    DT_PROP(DT_GPIO_CTLR(DT_DRV_INST(inst), gpio_pha), label)

    DT_INST_GPIO_LABEL_BY_IDX(inst, gpio_pha, idx)

    DT_PROP(DT_GPIO_CTLR_BY_IDX(DT_DRV_INST(inst), gpio_pha, idx), label)

    DT_SPI_DEV_CS_GPIOS_LABEL(spi_dev)

    DT_PROP(DT_SPI_DEV_CS_GPIOS_CTLR(spi_dev), label)

    DT_INST_SPI_DEV_CS_GPIOS_LABEL(inst)

    DT_PROP(DT_SPI_DEV_CS_GPIOS_CTLR(DT_DRV_INST(inst)), label)

    DT_LABEL(node_id)

    DT_PROP(node_id, label)

    DT_BUS_LABEL(node_id)

    DT_PROP(DT_BUS(node_id), label)

    DT_INST_LABEL(inst)

    DT_INST_PROP(inst, label)

    DT_INST_BUS_LABEL(inst)

    DT_PROP(DT_BUS(DT_DRV_INST(inst)), label)

Multi-level Interrupts

  • For platforms that enabled :kconfig:option:`CONFIG_MULTI_LEVEL_INTERRUPTS`, the IRQ variant of the Devicetree macros now return the as-seen value in the devicetree instead of the Zephyr multilevel-encoded IRQ number. To get the IRQ number in Zephyr multilevel-encoded format, use IRQN variant instead. For example, consider the following devicetree:

    plic: interrupt-controller@c000000 {
        riscv,max-priority = <7>;
        riscv,ndev = <1024>;
        reg = <0x0c000000 0x04000000>;
        interrupts-extended = <&hlic0 11>;
        interrupt-controller;
        compatible = "sifive,plic-1.0.0";
        #address-cells = <0x0>;
        #interrupt-cells = <0x2>;
};

uart0: uart@10000000 {
        interrupts = <10 1>;
        interrupt-parent = <&plic>;
        clock-frequency = <0x384000>;
        reg = <0x10000000 0x100>;
        compatible = "ns16550";
        reg-shift = <0>;
};

    plic is a second level interrupt aggregator and uart0 is a child of plic. DT_IRQ_BY_IDX(DT_NODELABEL(uart0), 0, irq) will return 10 (as-seen value in the devicetree), while DT_IRQN_BY_IDX(DT_NODELABEL(uart0), 0) will return (((10 + 1) << CONFIG_1ST_LEVEL_INTERRUPT_BITS) | 11).

    Drivers and applications that are supposed to work in multilevel-interrupt configurations should be updated to use the IRQN variant, i.e.:

    • DT_IRQ(node_id, irq) -> DT_IRQN(node_id)
    • DT_IRQ_BY_IDX(node_id, idx, irq) -> DT_IRQN_BY_IDX(node_id, idx)
    • DT_IRQ_BY_NAME(node_id, name, irq) -> DT_IRQN_BY_NAME(node_id, name)
    • DT_INST_IRQ(inst, irq) -> DT_INST_IRQN(inst)
    • DT_INST_IRQ_BY_IDX(inst, idx, irq) -> DT_INST_IRQN_BY_IDX(inst, idx)
    • DT_INST_IRQ_BY_NAME(inst, name, irq) -> DT_INST_IRQN_BY_NAME(inst, name)

Analog-to-Digital Converter (ADC)

Bluetooth HCI

Controller Area Network (CAN)

  • The native Linux SocketCAN driver, which can now be used in both :ref:`native_posix<native_posix>` and :ref:`native_sim<native_sim>` with or without an embedded C-library, has been renamed to reflect this:

  • Two new structures for holding common CAN controller driver configuration (struct can_driver_config) and data (struct can_driver_data) fields were introduced. Out-of-tree CAN controller drivers need to be updated to use these new, common configuration and data structures along with their initializer macros.

  • The optional can_get_max_bitrate_t CAN controller driver callback was removed in favor of a common accessor function. Out-of-tree CAN controller drivers need to be updated to no longer supply this callback.

  • The CAN transceiver API function :c:func:`can_transceiver_enable` now takes a :c:type:`can_mode_t` argument for propagating the CAN controller operational mode to the CAN transceiver. Out-of-tree CAN controller and CAN transceiver drivers need to be updated to match this new API function signature.

  • The CAN_FILTER_FDF flag for filtering classic CAN/CAN FD frames was removed since no known CAN controllers implement support for this. Applications can still filter on classic CAN/CAN FD frames in their receive callback functions as needed.

  • The CAN_FILTER_DATA and CAN_FILTER_RTR flags for filtering between Data and Remote Transmission Request (RTR) frames were removed since not all CAN controllers implement support for individual RX filtering based on the RTR bit. Applications can now use :kconfig:option:`CONFIG_CAN_ACCEPT_RTR` to either accept incoming RTR frames matching CAN filters or reject all incoming CAN RTR frames (the default). When :kconfig:option:`CONFIG_CAN_ACCEPT_RTR` is enabled, applications can still filter between Data and RTR frames in their receive callback functions as needed.

  • The :dtcompatible:`st,stm32h7-fdcan` CAN controller driver now supports configuring the domain/kernel clock via devicetree. Previously, the driver only supported using the PLL1_Q clock for kernel clock, but now it defaults to the HSE clock, which is the chip default. Boards that use the PLL1_Q clock for FDCAN will need to override the clocks property as follows:

    &fdcan1 {
        clocks = <&rcc STM32_CLOCK_BUS_APB1_2 0x00000100>,
                 <&rcc STM32_SRC_PLL1_Q FDCAN_SEL(1)>;
};

Display

  • ILI9XXX based displays now use the MIPI DBI driver class. These displays must now be declared within a MIPI DBI driver wrapper device, which will manage interfacing with the display. Note that the cmd-data-gpios pin has changed polarity with this update, to align better with the new dc-gpios name. For an example, see below:

    /* Legacy ILI9XXX display definition */
&spi2 {
    ili9340: ili9340@0 {
        compatible = "ilitek,ili9340";
        reg = <0>;
        spi-max-frequency = <32000000>;
        reset-gpios = <&gpio0 6 GPIO_ACTIVE_LOW>;
        cmd-data-gpios = <&gpio0 12 GPIO_ACTIVE_LOW>;
        rotation = <270>;
        width = <320>;
        height = <240>;
    };
};

/* New display definition with MIPI DBI device */

mipi_dbi {
    compatible = "zephyr,mipi-dbi-spi";
    reset-gpios = <&gpio0 6 GPIO_ACTIVE_LOW>;
    dc-gpios = <&gpio0 12 GPIO_ACTIVE_HIGH>;
    spi-dev = <&spi2>;
    #address-cells = <1>;
    #size-cells = <0>;

    ili9340: ili9340@0 {
        compatible = "ilitek,ili9340";
        reg = <0>;
        mipi-max-frequency = <32000000>;
        rotation = <270>;
        width = <320>;
        height = <240>;
    };
};

Flash

General Purpose I/O (GPIO)

Input

Interrupt Controller

  • The function signature of the isr_t callback function passed to the shared_irq interrupt controller driver API via :c:func:`shared_irq_isr_register()` has changed. The callback now takes an additional irq_number parameter. Out-of-tree users of this API will need to be updated.

    (:github:`66427`)

Renesas RA Series Drivers

Sensors

  • The :dtcompatible:`st,lsm6dsv16x` sensor driver has been changed to support configuration of both int1 and int2 pins. The DT attribute irq-gpios has been removed and substituted by two new attributes, int1-gpios and int2-gpios. These attributes must be configured in the Device Tree similarly to the following example:

    / {
    lsm6dsv16x@0 {
        compatible = "st,lsm6dsv16x";

        int1-gpios = <&gpioa 4 GPIO_ACTIVE_HIGH>;
        int2-gpios = <&gpiod 11 GPIO_ACTIVE_HIGH>;
        drdy-pin = <2>;
    };
};

Serial

  • Runtime configuration is now disabled by default for Nordic UART drivers. The motivation for the change is that this feature is rarely used and disabling it significantly reduces the memory footprint.

Timer

  • The :dtcompatible:`st,stm32-lptim` lptim which is selected for counting ticks during low power modes is identified by stm32_lp_tick_source in the device tree as follows. The stm32_lptim_timer driver has been changed to support this.

    stm32_lp_tick_source: &lptim1 {
        status = "okay";
};

Bluetooth

Bluetooth Mesh

Bluetooth Audio

  • The BT_AUDIO_CODEC_LC3_* values from <zephyr/bluetooth/audio/lc3.h> have moved to <zephyr/bluetooth/audio/audio.h> and have the LC3 part of their names replaced by a more semantically correct name: e.g. BT_AUDIO_CODEC_LC3_CHAN_COUNT is now BT_AUDIO_CODEC_CAP_TYPE_CHAN_COUNT, BT_AUDIO_CODEC_LC3_FREQ is now BT_AUDIO_CODEC_CAP_TYPE_FREQ, and BT_AUDIO_CODEC_CONFIG_LC3_FREQ is now BT_AUDIO_CODEC_CFG_FREQ, etc. Similarly the enumerations have also been renamed. E.g. bt_audio_codec_config_freq is now bt_audio_codec_cfg_freq, bt_audio_codec_capability_type is now bt_audio_codec_cap_type, bt_audio_codec_config_type is now bt_audio_codec_cfg_type, etc. (:github:`67024`)
  • The ts parameter of :c:func:`bt_bap_stream_send` has been removed. :c:func:`bt_bap_stream_send` now always sends without timestamp. To send with a timestamp, :c:func:`bt_bap_stream_send_ts` can be used.
  • The ts parameter of :c:func:`bt_cap_stream_send` has been removed. :c:func:`bt_cap_stream_send` now always sends without timestamp. To send with a timestamp, :c:func:`bt_cap_stream_send_ts` can be used.

Networking

  • The CoAP public API has some minor changes to take into account. The :c:func:`coap_remove_observer` now returns a result if the observer was removed. This change is used by the newly introduced :ref:`coap_server_interface` subsystem. Also, the request argument for :c:func:`coap_well_known_core_get` is made const. (:github:`64265`)
  • CoAP observer events have moved from a callback function in a CoAP resource to the Network Events subsystem. The CONFIG_COAP_OBSERVER_EVENTS configuration option has been removed. (:github:`65936`)
  • The CoAP public API function :c:func:`coap_pending_init` has changed. The parameter retries is replaced with a pointer to :c:struct:`coap_transmission_parameters`. This allows to specify retransmission parameters of the confirmable message. It is safe to pass a NULL pointer to use default values. (:github:`66482`)
  • The CoAP public API functions :c:func:`coap_service_send` and :c:func:`coap_resource_send` have changed. An additional parameter pointer to :c:struct:`coap_transmission_parameters` has been added. It is safe to pass a NULL pointer to use default values. (:github:`66540`)
  • The IGMP multicast library now supports IGMPv3. This results in a minor change to the existing api. The :c:func:`net_ipv4_igmp_join` now takes an additional argument of the type const struct igmp_param *param. This allows IGMPv3 to exclude/include certain groups of addresses. If this functionality is not used or available (when using IGMPv2), you can safely pass a NULL pointer. IGMPv3 can be enabled using the Kconfig CONFIG_NET_IPV4_IGMPV3. (:github:`65293`)
  • The network stack now uses a separate IPv4 TTL (time-to-live) value for multicast packets. Before, the same TTL value was used for unicast and multicast packets. The IPv6 hop limit value is also changed so that unicast and multicast packets can have a different one. (:github:`65886`)
  • The Ethernet phy APIs defined in <zephyr/net/phy.h> are removed from syscall list. The APIs were marked as callable from usermode but in practice this does not work as the device cannot be accessed from usermode thread. This means that the API calls will need to made from supervisor mode thread.
  • The zperf ratio between mbps and kbps, kbps and bps is changed to 1000, instead of 1024, to align with iperf ratios.
  • For network buffer pools maximum allocation size was added to a common structure struct net_buf_data_alloc as a new field max_alloc_size. Similar member data_size of struct net_buf_pool_fixed that was specific only for buffer pools with a fixed size was removed.

Other Subsystems

LoRaWAN

  • The API to register a callback to provide battery level information to the LoRaWAN stack has been renamed from lorawan_set_battery_level_callback to :c:func:`lorawan_register_battery_level_callback` and the return type is now void. This is more consistent with similar functions for downlink and data rate changed callbacks. (:github:`65103`)

MCUmgr

  • MCUmgr applications that make use of serial transports (shell or UART) must now select :kconfig:option:`CONFIG_CRC`, this was previously erroneously selected if MCUmgr was enabled, when for non-serial transports it was not needed. (:github:`64078`)

Shell

ZBus

Userspace

Architectures

Xtensa