C
Getting started
Before you start porting, ensure that all the prerequisites for Qt Quick Ultralite are met. This guide uses CMake in all the examples as Qt Quick Ultralite depends on the CMake build system.
This guide uses a dummy platform, example-baremetal
, as an example for the porting steps. You can create your platform port based on this dummy platform or create one from scratch.
Setting up a Qt Quick Ultralite platform port project
Qt Quick Ultralite has all its supported platforms under platform
directory. All platforms are under the boards
subdirectory, where they are categorized based on the platform manufacturer's name. For example, the example-baremetal
platform port's manufacturer is qt and the port can be found from platform\boards\qt\example-baremetal
.
BOARD_MANUFACTURER_NAME is a variable that is set by qul_private_find_and_get_board_manufacturer_name
macro. It is used to search for the given platform from the boards
directory and return the directory where the specified port for the board resides.
To make your platform visible to Qt Quick Ultralite's CMake scripts, create a new directory for the platform:
mkdir platform/boards/<MANUFACTURER_NAME>/<YOUR_PLATFORM>
md platform\boards\<MANUFACTURER_NAME>\<YOUR_PLATFORM>
Where <MANUFACTURER_NAME> and <YOUR_PLATFORM> can be named however you want.
You must add a CMakeLists.txt
file for both the <MANUFACTURER_NAME> and the <YOUR_PLATFORM> directories. The CMakeLists.txt
under <YOUR_PLATFORM> is configured in Creating the configuration file for your platform. The one under <MANUFACTURER_NAME> must contain at least the following:
include(CMakeDependentOption) string(TOLOWER ${QUL_PLATFORM} board_name) add_subdirectory(${CMAKE_CURRENT_LIST_DIR}/${board_name})
You can also copy the contents of the example-baremetal
platform to use as a reference.
Note: While all supported platforms have either baremetal
or freertos
appended to their names, the platform need not have either of them in its name.
Project structure
Qt Quick Ultralite does not have a strict structure that you have to follow. However, some things must be present and configured for the platform to be able to compile with Qt Quick Ultralite's CMake scripts.
cmake
directory
Your project must have a cmake
directory containing compiler and board information for Qt Quick Ultralite to be able to recognize and compile the platform. You may use the platform\boards\qt\example-baremetal\cmake
directory as the basis for your platform's cmake directory. Note that example-baremetal
project's cmake
directory contains configuration for ARM GCC compiler and IAR compiler. If you are using a compiler other than ARM GCC, Green Hills, or IAR compilers, additional configuration is needed. For more information, see Using a custom toolchain.
The cmake directory has a following structure:
<YOUR_PLATFORM> |-cmake | |-<YOUR_COMPILER> | | |-platform.cmake | | |-<YOUR_PLATFORM>.json | | |-<YOUR_LINKER_SCRIPT> | |-BoardArchitectureConfig.cmake | |-BoardDefaults.qmlprojectconfig | |-BSPConfig.cmake | |-LinkerScriptConfig.cmake
Defining default variables for the platform
Since Qt for MCUs 2.3, BoardDefaults.cmake
file is removed, changing the platform file structure. All information in this file is organized in following way:
BoardDefaults.qmlprojectconfig
contains Qt Quick Ultralite engine-specific configurations the target board.BoardArchitectureConfig.cmake
contains information about the platform architecture.LinkerScriptConfig.cmake
contains linker script configurations. See Adding your linker script to the project- Platform-specific configurations were moved to the platform
CMakeLists.txt
file. See Setting platform properties
See QmlProject Manual for more information.
BoardDefaults.qmlprojectconfig
naming scheme
A platform port can have more than one BoardDefaults.qmlprojectconfig
files depending on different board or display configurations. To be able to support all those configurations, use the following naming convention:
BoardDefaults_<color_depth>bpp_<default>.qmlprojectconfig
where:
- The
color_depth
should be value set to theQUL_COLOR_DEPTH
CMake variable. This value is used also to determine the span of available configurations based on multiple qmlprojectconfig files existing in the platform cmake directory. - If there are multiple configurations, use the
default
keyword for one of them to indicate a default configuration.
The following table describes different example scenarios and the corresponding configuration file name:
Scenario | Behavior |
---|---|
Only one BoardDefaults.qmlprojectconfig file exists.cmake |- BoardDefaults.qmlprojectconfig | In a scenario like this where color_depth information is not part of the file name, explicitly provide the QUL_COLOR_DEPTH option to the CMake command. |
Only one BoardDefaults_<color_depth>.qmlprojectconfig file exist.cmake |- BoardDefaults_32bpp.qmlprojectconfig | When using configurations that include the color_depth information in the file name, there is no need to provide the -DQUL_COLOR_DEPTH option to the CMake command. |
Multiple BoardDefaults_<color_depth>.qmlprojectconfig files exist. Non of it uses default keyword.cmake |- BoardDefaults_8bpp.qmlprojectconfig |- BoardDefaults_16bpp.qmlprojectconfig |- BoardDefaults_32bpp.qmlprojectconfig | In this scenario where multiple qmlprojectconfig files include the color_depth information in the file name then explicitly provide the QUL_COLOR_DEPTH option to the CMake command. |
Multiple BoardDefaults_<color_depth>.qmlprojectconfig files exist. One of it contains default keyword.cmake |- BoardDefaults_8bpp_default.qmlprojectconfig |- BoardDefaults_16bpp.qmlprojectconfig |- BoardDefaults_32bpp.qmlprojectconfig | When one of the configurations contains the default keyword in the file name, it will be picked automatically. To choose a different one explicitly provide the QUL_COLOR_DEPTH option to the CMake command. |
Note: If the qmlprojectconfig
file is not named according to the convention, explicitly provide the -DQUL_PLATFORM_BOARD_DEFAULTS_QMLPROJECTCONFIG=<path_to_qmlprojectconfig_file>
option to the CMake command.
Setting platform properties
Since Qt for MCUs 2.3 platform related configurations are set in the target platform CMakeLists.txt
file as the Platform
target properties. List of the all properties with default values and descriptions are presented in following table:
Common properties:
Property name | Default value | Decription |
---|---|---|
QUL_PLATFORM_DEFAULT_SCREEN_WIDTH | 480 | The default screen width in pixels. Currently used only by the desktop backend. |
QUL_PLATFORM_DEFAULT_SCREEN_HEIGHT | 272 | The default screen height in pixels. Currently used only by the desktop backend. |
QUL_PLATFORM_DEFAULT_TEXT_CACHE_ENABLED | OFF | The default value for text caching on the target platform. See QUL_PLATFORM_DEFAULT_TEXT_CACHE_ENABLED for more information. |
QUL_PLATFORM_DEFAULT_TEXT_CACHE_SIZE | 24*1024 | The default size for text cache on the target platform. See QUL_PLATFORM_DEFAULT_TEXT_CACHE_SIZE for more information. |
QUL_PLATFORM_DEFAULT_NUM_FRAMES_TO_PRESERVE_ASSETS | 0 | The default number of frames to preserve assets on the target platform. See QUL_PLATFORM_DEFAULT_NUM_FRAMES_TO_PRESERVE_ASSETS for more information. |
QUL_PLATFORM_REQUIRED_IMAGE_ALIGNMENT | 1 | The minimum alignment required for image data on the target platform. See QUL_PLATFORM_REQUIRED_IMAGE_ALIGNMENT for more information. |
QUL_PLATFORM_REQUIRED_PIXEL_WIDTH_ALIGNMENT | 1 | The image width will be a multiple of this value on the target platform. See QUL_PLATFORM_REQUIRED_PIXEL_WIDTH_ALIGNMENT for more information. |
QUL_PLATFORM_EXCLUDED_EXAMPLES | List of examples that should be excluded from the build. It is defined in the CMake list format, where each value is delimited or separated by a semicolon. The following example disables the set_target_properties(Platform PROPERTIES QUL_PLATFORM_EXCLUDED_EXAMPLES "freertos_multitask;image_cache" ) | |
QUL_PLATFORM_EXCLUDED_DEMOS | List of demos that should be excluded from the build. It is defined in the CMake list format, where each value is delimited or separated by a semicolon. The following example disables the set_target_properties(Platform PROPERTIES QUL_PLATFORM_EXCLUDED_DEMOS "automotive;motor_cluster" ) | |
QUL_PLATFORM_EXCLUDED_TESTS | List of tests that should be excluded from the build. It is defined in the CMake list format, where each value is delimited or separated by a semicolon. The following example disables the set_target_properties(Platform PROPERTIES QUL_PLATFORM_EXCLUDED_TESTS "controls;flickable" ) |
Cypress platform-specific properties:
Property name | Decription | |
---|---|---|
QUL_PRIVATE_INFINEON_RESOURCE_GENERATOR | Path to ResourceGenerator.exe binary file, which is found in Cypress SDK directory. Set this property to compile the resources. |
NXP platform-specific properties:
Property name | Decription |
---|---|
NXP_CHIP_NAME | Name of NXP chip family name, such as MIMXRT1052xxxxB . Set this variable to be able to flash targets. |
NXP_CONNECT_SCRIPT | Name of the connect script from MCUXpressoIDE , such as RT1050_connect.scp . Set this variable to be able to connect to the flash targets. |
NXP_RESET_SCRIPT | Name of the reset script from MCUXpressoIDE , such as RT1170_reset.scp . Currently this variable is required only by NXP RT1170 to be able to properly restart board after flashing. |
NXP_PARTFILES_DIR | Path to directory containing NXP partfiles in XML format. Set this variable to be able to use it while flashing targets. |
STM platform-specific properties:
Property name | Decription |
---|---|
STM32_EXTERNAL_LOADER | Path to the STM32 external loader file, to be able to flash the external memory. |
Example properties set in platform CMakeLists.txt
:
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;layers;multiscreen;shapes" QUL_PLATFORM_EXCLUDED_TESTS "layers;layer_transparency;pathstroke;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" )
Specifying compile and link options for the platform
platform.cmake
contains compile and link options specific to your platform. Architecture options can be found in the files for the specific architecture.
Specifying vendor SDK specific settings
BSPConfig.cmake
contains all settings that are required for using functions from the vendor SDK, like GPIO or interrupt handlers.
See Platform SDK Config.
These usually are defines for a specific board and include paths.
target_compile_definitions(PlatformBSPConfig INTERFACE # Platform SDK specific compile definitions USE_HAL_DRIVER ) target_include_directories(PlatformBSPConfig INTERFACE # Platform SDK specific include directories # eg. ${QUL_BOARD_SDK_DIR}/Drivers/BSP/STM32F769I-Discovery/ )
Creating the platform kit configuration file
<YOUR_PLATFORM>.json
file is used to create a platform kit in the Qt Creator IDE. It represents a target in Qt Creator terms.
Note: This file is only required if you are going to use the Qt Creator IDE.
Note: Custom compilers are not supported in Qt Creator.
Main elements of the kit's JSON file are:
Attribute | Description |
---|---|
qulVersion | Qt Quick Ultralite version the platform is built against. By default, this is set to @CMAKE_PROJECT_VERSION@ . |
platform | Object containing the platform's name, a list of supported color depths, the vendor/manufacturer name and 3rd party packages. |
toolchain | Object containing the details about the toolchain that the platform uses. This is split into two objects - compiler and file. The former helps finding the compiler and the latter contains the location of the toolchain's CMake file Using a custom toolchain. |
boardSdk | Object containing details of the SDK the platform uses. |
freeRTOS | Object containing details of the FreeRTOS support of the platform. This part is not present in baremetal devices. |
The JSON file contains a collection of json objects used by Qt Creator to create the kit. Each object represents a 3rd party dependency (package) and holds a path to the dependency. The path will later be forwarded to different outputs:
- A cmake variable used to configure the project (e.g. -DFREERTOS_DIR=<path>)
- A directory that will be added to PATH environment variable
The package value can be read by QtCreator from the folowing locations, in order:
- Qt Creator settings.
- The correspoding Environmental variable (
envVar
). - The
defaultValue
defined in the json file.
In summary the packages required for a correct kit to be generated are:
- Platform's 3rd party packages (cmakeEntries array).
- The toolchain packages (a compiler and a toolchain file).
- BoardSdk package
- FreeRTOS package (when applicable)
Each package has the following attributes:
Attribute | Description |
---|---|
cmakeVar | Output cmake variable |
setting | QtCreator setting name which should be set by the Qt Installer. |
envVar | Environment variable name to override value from settings. |
label | Label shown in UI of the MCU support plugin (Edit -> Preferences -> Devices -> MCU) |
defaultValue | Default value that is used when setting or environment variable is not set. Split into separate values for windows and linux. |
versions | List of versions that are supported. |
versionDetection | Information used for version detection. |
validation | Path suffix used to validate the package. |
The platform json kit file can be validated using a schema file found in $QUL_ROOT/kits/schemas/ and a jsonschema validation tool of choice, an online solution can be found here. The schemas are using the Draft-2020-12 specification. Currently only "schema-2.3" is provided to validate kits that works with QtMCUs 2.3.0 and higher.
Main elements of the kit's JSON file are: Here is an example JSON file (example-baremetal.json
):
{ "qulVersion": "@CMAKE_PROJECT_VERSION@", "compatVersion": "@COMPATIBILITY_VERSION@", "platform": { "colorDepths": [ 16 ], "id": "EXAMPLE-BAREMETAL", "vendor": "Vendor Name" }, "toolchain": { "id": "armgcc", "versions": [ "10.3.1" ], "compiler": { "id": "ARMGCC_DIR", "label": "GNU Arm Embedded Toolchain", "cmakeVar": "QUL_TARGET_TOOLCHAIN_DIR", "envVar": "ARMGCC_DIR", "setting": "GNUArmEmbeddedToolchain", "type": "path", "optional": false, "versionDetection": { "filePattern": { "windows": "bin/arm-none-eabi-g++.exe", "linux": "bin/arm-none-eabi-g++" }, "executableArgs": "--version", "regex": "\\b(\\d+\\.\\d+\\.\\d+)\\b" }, "detectionPath": { "windows": "bin/arm-none-eabi-g++.exe", "linux": "bin/arm-none-eabi-g++" } }, "file": { "id": "ARMGCC_CMAKE_TOOLCHAIN_FILE", "cmakeVar": "CMAKE_TOOLCHAIN_FILE", "type": "file", "defaultValue": "%{Qul_ROOT}//lib/cmake/Qul/toolchain/armgcc.cmake", "visible": false, "optional": false } }, "boardSdk": { "versions": [ "1.16.0" ], "id": "EXAMPLE_SDK_DIR", "label": "Board SDK", "cmakeVar": "QUL_BOARD_SDK_DIR", "type": "path", "optional": false } }
Here is the JSON file for the IAR compiler. It has a few differences compared to the previous example:
{ "qulVersion": "@CMAKE_PROJECT_VERSION@", "compatVersion": "@COMPATIBILITY_VERSION@", "platform": { "id": "EXAMPLE-BAREMETAL", "vendor": "Vendor Name", "colorDepths": [ 16 ] }, "toolchain": { "id": "iar", "versions": [ "9.20.4" ], "compiler": { "id": "IARToolchain", "setting": "IARToolchain", "envVar": "IAR_ARM_COMPILER_DIR", "label": "IAR ARM Compiler", "cmakeVar": "QUL_TARGET_TOOLCHAIN_DIR", "type": "path", "versionDetection": { "filePattern": { "windows": "bin/iccarm.exe", "linux": "bin/iccarm" }, "executableArgs": "--version", "regex": "\\bV(\\d+\\.\\d+\\.\\d+)\\.\\d+\\b" }, "detectionPath": { "windows": "bin/iccarm.exe", "linux": "bin/iccarm" }, "defaultValue": { "windows": "%{Env:PROGRAMFILES}/IAR Systems/Embedded Workbench 9.0/arm", "linux": "/opt/iarsystems/bxarm-9.20.4/arm" }, "optional": false }, "file": { "id": "IAR_CMAKE_TOOLCHAIN_FILE", "cmakeVar": "CMAKE_TOOLCHAIN_FILE", "type": "file", "defaultValue": "%{Qul_ROOT}/lib/cmake/Qul/toolchain/iar.cmake", "visible": false, "optional": false } }, "boardSdk": { "versions": [ "1.16.0" ], "id": "EXAMPLE_SDK_DIR", "label": "Board SDK", "cmakeVar": "QUL_BOARD_SDK_DIR", "type": "path", "optional": false } }
Adding your linker script
cmake\<YOUR_COMPILER>\<YOUR_LINKER_SCRIPT>
is the linker script your platform uses. Qt Quick Ultralite uses the linker script to organize the data and code in the final binary to appropriate memory addresses. Setting up of the script is described in detail with an example in the Linker script setup section.
Adding your linker script to the project
A default linker script can be set in LinkerScriptConfig.cmake
to be used by CMake. example-baremetal
platform:
if(IAR) qul_platform_add_default_linker_script("${QUL_PRIVATE_PLATFORM_BOARD_CMAKE_DIR}/${QUL_COMPILER_NAME}/example-platform.icf") else() qul_platform_add_default_linker_script("${QUL_PRIVATE_PLATFORM_BOARD_CMAKE_DIR}/${QUL_COMPILER_NAME}/example-platform.ld") endif()
The argument defines the linker script to use. For more information, see Using a custom toolchain.
Creating the configuration file for your platform
platform\<YOUR_PLATFORM>\CMakeLists.txt
is your platform's primary configuration file. It specifies all sources, include directories, compile definitions, and other parameters your platform requires. For more information about the CMake syntax, see CMake Documentation. You can also use platform\boards\qt\example-baremetal\CMakeLists.txt
as a basis for your platform's CMakeLists.txt
.
Note: When you are defining sources, include directories or other attributes for your platform, you must specify Platform
as the target for these definitions.
The following is the CMakeLists.txt
for the example-baremetal
platform:
target_sources(Platform PRIVATE examplelayerengine.cpp examplepath.cpp examplestroker.cpp examplequeue.cpp platform_context.cpp devicelink.cpp mem.cpp ${PLATFORM_COMMON_SRC_DIR}/singlepointtoucheventdispatcher.cpp ${PLATFORM_COMMON_SRC_DIR}/platform.cpp # Add platform source files here ) target_include_directories(Platform PRIVATE # Add platform specific include directories here ) target_compile_definitions(Platform PRIVATE # Insert platform specific compile flags here # e.g. APPLICATION_ADDRESS=0x90000000 )
For IAR compiler, use the following example as a reference:
target_sources(Platform PRIVATE examplelayerengine.cpp examplepath.cpp examplestroker.cpp examplequeue.cpp platform_context.cpp devicelink.cpp mem-iar.cpp ${PLATFORM_COMMON_SRC_DIR}/singlepointtoucheventdispatcher.cpp ${PLATFORM_COMMON_SRC_DIR}/platform.cpp # Add platform source files here ) target_include_directories(Platform PRIVATE # Add platform specific include directories here ) target_compile_definitions(Platform PRIVATE # Insert platform specific compile flags here # e.g. APPLICATION_ADDRESS=0x90000000 )
The example CMakeLists.txt
has two files defined in sources: platform_context.cpp
and mem.cpp
. These files contain sample code for basic functions and memory allocation API respectively. The contents of these files are documented in Implementing basic functions and Memory allocation in Qt Quick Ultralite platform abstraction chapters.
Creating flash targets
Qt Quick Ultralite CMake scripts offer support to generate targets for flashing binaries to the device. This is useful in the application development phase, where you might have to build and flash the binaries often. It offers a single command to build and flash the binary.
The following must be done in order to get flash targets generated:
- Create a new file called
ExecutableHook.cmake
under theplatform\boards\<MANUFACTURER_NAME>\<YOUR_PLATFORM>\cmake
directory. - Add the following function to
ExecutableHook.cmake
:function(add_executable_hook name) add_custom_target("flash_${name}" COMMAND <COMMAND_FOR_YOUR_FLASHER>) message(STATUS "Added flash target flash_${name}") endfunction()
The name argument is the target application's name. For minimal example, name would be minimal and the resulting flash target is flash_minimal. <COMMAND_FOR_YOUR_FLASHER> is the command you use to flash built binaries to the target device. Your binary can be found using
$<TARGET_FILE_DIR:${name}>/${name}.elf
. Depending on the compiler and the flashing tool, the generated binary might be in a format that is not ELF.
Running CMake for your platform should now output Added flash target flash_<EXAMPLE/DEMO>
. If you've copied example-baremetal
project, you can use the following command to test whether flashing runs your flasher correctly:
nmake flash_minimal
However, your platform is still quite barebones. If your build does not succeed, continue reading this guide and try again at a later time.
Linker script setup
Linker script is a file containing information about the platform's memory configuration. It also specifies regions where application code and data resides. The linker script is used by the toolchain's linker to organize the data and code in the final binary at appropriate memory addresses. In this section, you will get to know what needs to be configured in your linker script to get Qt Quick Ultralite working.
Following examples are snippets from platform\boards\qt\example-baremetal\cmake\armgcc\example-platform.ld
. There is also a variant for IAR linkers available at platform\boards\qt\example-baremetal\cmake\iar\example-platform.icf
for your reference. You can copy these files to your project to use as a basis for your own linker script. However, it is recommended that you have your own linker script where you insert additional memory sections explained here.
Note: The examples use GNU linker script syntax. Some things may be implemented differently between different toolchain linker scripts. Refer your toolchain's manual for more information about the syntax for linker scripts.
In order to assign program sections to the device, its memory layout must be configured:
MEMORY { FLASH (rx) : ORIGIN = 0x08000000, LENGTH = 2048K /* internal flash */ RAM (xrw) : ORIGIN = 0x20000000, LENGTH = 512K /* internal sram */ SDRAM (xrw) : ORIGIN = 0xc0400000, LENGTH = 6M /* external sdram memory */ SDRAM_PRELOAD (xrw) : ORIGIN = 0xc0a00000, LENGTH = 2M /* external sdram memory - preload */ QSPI (rx) : ORIGIN = 0x90000000, LENGTH = 64M /* external flash */ }
This layout has five regions: FLASH, RAM, SDRAM, SDRAM_PRELOAD and QSPI. RAM, SDRAM and SDRAM_PRELOAD have execute, read, and write access. Whereas, FLASH and QSPI are read-only flash memories and thus have only read and execute access.
Note: Avoid using this layout as-is for your platform's memory layout, as it may lead to errors when flashing the binary or attempting to run it on the device. Refer your target platform's manual for the memory layout and appropriate memory addresses for your device.
In this example resource data is stored in the QSPI flash memory region. QulResourceData
name is hardcoded and represents the default section for the image resources. For adding additional resource sections see Managing Resources.
QulFontResourceData
name is hardcoded and represents the default section for the font files and glyph data. Custom font files section is configured with MCU.Config.fontFilesStorageSection property and glyphs section with MCU.Config.glyphsStorageSection.
The QulModuleResourceData
section is reserved by Qt Quick Ultralite to place its internal resources. User-specified resources should not be placed in it.
QulFontResourceData : { . = ALIGN(4); *(QulFontResourceData) } > QSPI QulModuleResourceData : { . = ALIGN(4); __ModuleResourceDataCacheStart = .; *(QulModuleResourceData) . = ALIGN(4); __ModuleResourceDataCacheEnd = .; } > SDRAM AT> QSPI __ModuleResourceDataStart = LOADADDR(QulModuleResourceData); QulResourceData : { . = ALIGN(4); *(QulResourceData) } > QSPI
This example reserves space from the SDRAM for the preloadable resources with SDRAM_PRELOAD region. Symbols __preloadSdramStart
and __preloadSdramEnd
are defined for the resource preloading to determine the start and end address of the preload section:
__preloadSdramStart = ORIGIN(SDRAM_PRELOAD); __preloadSdramEnd = ORIGIN(SDRAM_PRELOAD) + LENGTH(SDRAM_PRELOAD);
Example platform adaptation creates pointers to the linker symbols:
extern uint8_t __preloadSdramStart; extern uint8_t __preloadSdramEnd; void *preloadSdramStart = &__preloadSdramStart; void *preloadSdramEnd = &__preloadSdramEnd;
By default the resources use DefaultPreload allocation type. Preload start and end address are used by the ExampleReversePreloadAllocator to determine the maximum size of the preload section.
PlatformInterface::MemoryAllocator *ExamplePlatform::memoryAllocator( PlatformInterface::MemoryAllocator::AllocationType type) { static ExampleMemoryAllocator exampleMemoryAllocator; static ExampleReversePreloadAllocator<4> examplePreloadAllocator(preloadSdramEnd, preloadSdramStart); static PlatformInterface::MemoryAllocator defaultMemoryAllocator; switch (type) { case PlatformInterface::MemoryAllocator::Image: return &exampleMemoryAllocator; case PlatformInterface::MemoryAllocator::DefaultPreload: return &examplePreloadAllocator; default: return &defaultMemoryAllocator; } }
Preloading can be disabled by returning nullptr
from the memory allocator for the DefaultPreload allocation type.
Preloading Qt Quick Ultralite internal resources
Qt Quick Ultralite internal resources contain the image data for example for the dials and buttons that are linked to the application from Qul::Controls
library. Internal resources do not support preloading with Qul::PlatformInterface::MemoryAllocator
.
In this example preloadable internal resource data is copied from the QSPI flash memory region to SDRAM.
__ModuleResourceDataCacheStart
, __ModuleResourceDataCacheEnd
, and __ModuleResourceDataStart
must also be defined. They are used in the platform code to load the resources from QSPI to SDRAM:
extern unsigned char __ModuleResourceDataStart; extern unsigned char __ModuleResourceDataCacheStart; extern unsigned char __ModuleResourceDataCacheEnd; memcpy(&__ModuleResourceDataCacheStart, &__ModuleResourceDataStart, &__ModuleResourceDataCacheEnd - &__ModuleResourceDataCacheStart);
For IAR compilers there need to be some section declarations included
#pragma section = "QulModuleResourceData" #pragma section = "QulModuleResourceData_init" char *__ModuleResourceDataStart = (char *) (__section_begin("QulModuleResourceData_init")); char *__ModuleResourceDataCacheStart = (char *) (__section_begin("QulModuleResourceData")); char *__ModuleResourceDataCacheEnd = (char *) (__section_end("QulModuleResourceData")); memcpy(__ModuleResourceDataCacheStart, __ModuleResourceDataStart, (unsigned) __ModuleResourceDataCacheEnd - (unsigned) __ModuleResourceDataCacheStart);
Make sure to check the example IAR linker script to see how to place these sections in your device memory.
Note: If preloading is not used, QulModuleResourceData
can be added to the linker script in the same way as QulResourceData
. In this case __ModuleResourceData*
symbols and memcpy
are not needed.
Using a custom toolchain
By default, Qt Quick Ultralite supports ARM GCC, GHS, or IAR toolchains across the supported platforms. However, it is possible to use your own compiler in the project.
To configure Qt Quick Ultralite for your toolchain, follow these steps:
- Add a
<YOUR_COMPILER>.cmake
tolib\cmake\Qul\toolchain
directory. - Create
<YOUR_COMPILER>
directory underplatform\boards\<MANUFACTURER_NAME>\<YOUR_PLATFORM>\cmake
. - Edit CMake configuration files in Qt Quick Ultralite
Adding <YOUR_COMPILER>.cmake
to the project
Add the <YOUR_COMPILER>.cmake
to the lib\cmake\Qul\toolchain
directory. This file configures your toolchain for the project. You can also use existing toolchain configurations as a basis for your compiler configuration.
The following variables should be set in the file:
Variable | Description |
---|---|
CMAKE_SYSTEM_NAME | The operating system CMake is building for. This must be set to Generic . |
CMAKE_SYSTEM_PROCESSOR | The processor CMake is building for. For example, if your target CPU is ARM CPU, set this to arm . |
COMPILER_FOLDER_NAME | Tells Qt Quick Ultralite project what compiler directory should be used for the target platform. This must match the name of the compiler directory in platform\boards\<MANUFACTURER_NAME>\<YOUR_PLATFORM>\cmake or else you will get errors during configuration. |
LINKER_SCRIPT_OPTION | This is used in qul_platform_add_default_linker_script to tell linker what flags to use. If you are not using LINKER_SCRIPT_OPTION , this is not needed. |
CMAKE_C_COMPILER | Path to the C compiler. |
CMAKE_CXX_COMPILER | Path to the C++ compiler. |
CMAKE_ASM_COMPILER | Path to the assembly compiler. This is not needed if you do not have assembly files in you platform. |
CMAKE_AR | Path to the toolchain's archiver. |
CMAKE_CXX_FLAGS_INIT | C++ compiler flags that are used in every configuration. |
CMAKE_C_FLAGS_INIT | C compiler flags that are used in every configuration. |
CMAKE_C_FLAGS_DEBUG | C compiler flags that are used in debug configuration in addition to the flags used in CMAKE_C_FLAGS_INIT . |
CMAKE_CXX_FLAGS_DEBUG | C++ compiler flags that are used in debug configuration in addition to the flags used in CMAKE_CXX_FLAGS_INIT . |
CMAKE_EXE_LINKER_FLAGS_INIT | Linker flags that are used in every configuration. |
In addition, you also need to set a variable that can be used to identify your compiler:
SET(<YOUR_COMPILER> ON)
This is used in other CMake files to configure additional things if needed.
<YOUR_COMPILER>
directory
Create a directory named <YOUR_COMPILER>
(or the name you set to COMPILE_FOLDER_NAME
in the previous step) for your toolchain in the platform\boards\<MANUFACTURER_NAME>\<YOUR_PLATFORM>\cmake
directory, and add all required files mentioned in the "cmake
directory" section.
CMake configuration files in Qt Quick Ultralite
Your toolchain may require some additional configuration in Qt Quick Ultralite.
The following files contain compiler-dependent configurations and might be worth checking out.
examples\CMakeLists.txt
has compiler-dependent warning flags, such asWall
andWerror
. If your compiler does not support already provided flags, add your own here.platform\CMakeLists.txt
If you are going to use same compiler on multiple platforms, it might be a good idea to write some common compilation options forPlatform
here.src\CMakeLists.txt
is used to buildCore
target. If your compiler has some specific arguments that must be taken into account, add them here.The file also includes configuration code for supported compilers. Check that your compiler can use the set parameters and modify the code if needed.
src\pngdecoders.cmake
adds LodePNG based PNG decoder to Qt Quick Ultralite. If your compiler has some specific arguments that must be taken into account when building the decoder, add them here.
Your compiler setup is ready to be used now. Test it by running CMake with -DCMAKE_TOOLCHAIN_FILE=path\to\Qt\QtMCUs\1.5.0\cmake\Qul\toolchain\<YOUR_COMPILER>.cmake
.
Available under certain Qt licenses.
Find out more.