Here are the changes to be aware of when porting a platform from Qt for MCUs 1.x or 2.x to Qt for MCUs 2.3 or higher.

The most important change is that the BoardDefaults.cmake is replaced by BoardDefaults.qmlprojectconfig from Qt Quick Ultralite 2.3 onwards. However, all platform configurations based on the older Qt Quick Ultralite versions (v2.0 - 2.2) can continue to use the CMake API.

Migration to BoardDefaults.qmlprojectconfig

Introduction of the BoardDefaults.qmlprojectconfig as default source of platform configuration caused several changes in the platforms file structure. See Platform porting guide for more information about this new approach.

Architecture builds

Qt for MCUs now uses architecture-based builds, so it's important to specify the target platform's architecture. This can be done by using the QUL_PLATFORM_ARCHITECTURE variable in BoardArchitectureConfig.cmake. See Architecture and Platform-specific Build Settings for more information.

Compile and link options for the platform

Rename the CompilationOptions.cmake file, containing the compiler and linker flags specific to your platform, to platform.cmake.

Linker script

Set the default linker script using the qul_platform_add_default_linker_script() CMake function in the platform's LinkerScriptConfig.cmake file:

qul_platform_add_default_linker_script("${CMAKE_CURRENT_LIST_DIR}/example-platform.ld")

In the previous Qt for MCUs versions, this was done using the LINKER_SCRIPT variable in LinkerScriptLoader.cmake,

Platform kit configuration file

The envVar attribute of the boardSdk attributes are replaced by the cmakeCacheEntries attribute. See the Creating a platform kit file for QtCreator section for more information.

Platform target name

The platform target has been renamed from QuickUltralitePlatform to Platform. Update the target_sources, target_include_directories, target_compile_definitions, and other relevant CMake commands to use the new target name.

Platform API

Move the implementation for the following fuctions into a sub-class of the Qul::Platform::PlatformContext class:

• initializeHardware
• initializeDisplay
• currentTimestamp
• exec
• rand
• scheduleEngineUpdate
• frameBufferingType
• beginFrame
• endFrame
• presentFrame
• availableScreens
• layerEngine
• waitUntilAsyncReadFinished
• flushCachesForAsyncRead
• memoryAllocator
• consoleWrite

In addition, add the initializePlatform member function to perform any platform initialization that is not directly hardware related.

Finally, implement the Qul::Platform::getPlatformInstance() function and make it return a pointer to a singleton platform instance.

Platform properties

The platform properties introduced in Qt for MCUs 2.3 to separate platform-specific configurations from Qt Quick Ultralite engine-related ones, which are defined in the BoardDefaults.qmlprojectconfig file. You can configure them in the platform's CMakeLists.txt, as shown in the following example:

set_target_properties(Platform
    PROPERTIES
        NXP_CHIP_NAME "MIMXRT1052xxxxB"
        NXP_CONNECT_SCRIPT "RT1050_connect.scp"
        # variables cannot be expanded that's why there is "\" before "$". It will be later evaluated at CMake runtime using
        # qul_private_evaluate_path_from_target_property() function
        NXP_PARTFILES_DIR "\${QUL_PLATFORM_TARGET_DIR}/../mimxrt1050-evk-common/cmake"
        QUL_PLATFORM_EXCLUDED_DEMOS "automotive;motor_cluster"
        QUL_PLATFORM_EXCLUDED_EXAMPLES "freertos_app_switch;imagedecoder;layers;multiscreen"
        QUL_PLATFORM_EXCLUDED_TESTS "layers;layers_with_shapes;layer_transparency;resource_storage_section"
        QUL_PRIVATE_USE_PLATFORM_CONFIGURATION_HEADER ON
    EXPORT_PROPERTIES "NXP_CHIP_NAME;NXP_CONNECT_SCRIPT;NXP_PARTFILES_DIR;QUL_PLATFORM_EXCLUDED_DEMOS;QUL_PLATFORM_EXCLUDED_EXAMPLES;QUL_PLATFORM_EXCLUDED_TESTS"
)

List of the all available platform properties are listed in the Platform porting guide. The following table covers only the renamed variables:

Resource preloading

QUL_STATIC_ASSET_SEGMENT is no longer used. Instead, memory for preloaded assets is allocated using the memory allocator returned from Qul::Platform::PlatformContext.

Refer to Memory allocation in Qt Quick Ultralite platform abstraction for details about how preloading can be implemented.

Resource storage location

Instead of using QUL_STATIC_ASSET_SEGMENT and QUL_STATIC_NO_PRELOAD_ASSET_SEGMENT, now the resources are by default placed in the QulResourceData, QulModuleResourceData, and QulFontResourceData segments. See Project setup for more information.

Defining OS configuration

Since Qt for MCUs 2.3, the QUL_OS value could be specified in two ways. It could either be passed as an option (-DQUL_OS=<os_name>) to the CMake call or name could be added at the end of QUL_PLATFORM name similar to all Qt Quick Ultralite reference platforms. For example, mimxrt1050-evk-baremetal.

Currently are supported only two configurations:

• baremetal
• FreeRTOS