C
Platform Migration Guide to Qt for MCUs 2.3
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.
Note: Since Qt for MCUs 2.3, the QUL_PLATFORM_ARCHITECTURE
variable is moved from BoardDefaults.cmake
to BoardArchitectureConfig.cmake
.
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 the platform kit configuration file 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
Note: availableScreens
and frameBufferingType
should be const
member functions.
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:
Qt for MCUs 1.9 CMake variables names | Qt for MCUs 2.x properties names |
---|---|
QUL_DEFAULT_SCREEN_WIDTH | QUL_PLATFORM_DEFAULT_SCREEN_WIDTH |
QUL_DEFAULT_SCREEN_HEIGHT | QUL_PLATFORM_DEFAULT_SCREEN_HEIGHT |
EXCLUDED_EXAMPLES | QUL_PLATFORM_EXCLUDED_EXAMPLES |
EXCLUDED_DEMOS | QUL_PLATFORM_EXCLUDED_DEMOS |
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 Getting started 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
Note: Since Qt for MCUs 2.0, OS
is renamed to QUL_OS
. If your existing port is based on a Qt for MCUs version older than v2.0, consider changing the variable accordingly.
Available under certain Qt licenses.
Find out more.