# 快速入门

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  .

The existence of a platform is checked in  platform\CMakeLists.txt  by checking whether a directory for that platform exists:

if(BOARD_MANUFACTURER_NAME) # This case is for all platforms that have a manufacturer eg. ST, NXP
add_subdirectory(boards/${BOARD_MANUFACTURER_NAME}) elseif((NOT QUL_PLATFORM_LOWERCASE STREQUAL "boards") AND EXISTS${CMAKE_CURRENT_LIST_DIR}/${QUL_PLATFORM_LOWERCASE}) # This case is for platforms without manufacturer eg. 'qt' add_subdirectory(${QUL_PLATFORM_LOWERCASE})
install_platform_packages()
else()
message(FATAL_ERROR "Following QUL_PLATFORM: ${QUL_PLATFORM} is not supported!") endif()  BOARD_MANUFACTURER_NAME is a variable that is set by  _qul_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: 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 you 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.

### 工程结构

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>
| | |-CompilationOptions.cmake
| | |-<YOUR_PLATFORM>.json
| | |-<YOUR_LINKER_SCRIPT>
| | |-LinkerScriptLoader.cmake
| |-BoardDefaults.cmake

##### Defining default variables for the platform

 BoardDefaults.cmake  is used to set default variables for the platform port. For Qt Quick Ultralite, following variables can be set here:

Variable Decription
 QUL_COLOR_DEPTH  How many bits per pixel is used to render content. This variable is optional and does not do anything if not used in the code.
 QUL_DEFAULT_SCREEN_WIDTH  The default screen width in pixels. Not setting this will result in an error.
 QUL_DEFAULT_SCREEN_HEIGHT  The default screen height in pixels. Not setting this will result in an error.
 QUL_DEFAULT_INTERNAL_ALPHA_OPTIONS  The default setting of when to use ARGB32_Premultiplied format for the image resources. If this value is not set, Qt Quick Ultralite defaults to "ForTransformations". See QUL_INTERNAL_ALPHA_OPTIONS for the details.
 OS  Operating system that is used in the project, used by  app_common  . Currently only  BareMetal  and  FreeRTOS  values are recognized. If this value is not set, Qt Quick Ultralite defaults to BareMetal. If you do not use  app_common  , this variable has no effect.
 EXCLUDED_EXAMPLES  List of examples that are excluded from the build.

The following example disables  freertos_multitask  and  image_cache  examples:

set(EXCLUDED_EXAMPLES
"freertos_multitask"
"image_cache"
CACHE STRING "List of examples excluded from build")

 EXCLUDED_DEMOS  List of demos that are excluded from the build.

The following example disables  automotive  and  motor_cluster  demos:

set(EXCLUDED_DEMOS
"automotive"
"motor_cluster"
CACHE STRING "List of demos excluded from build")


IF(NOT QUL_COLOR_DEPTH)
SET(QUL_COLOR_DEPTH 16)
ENDIF()
if(NOT QUL_DEFAULT_SCREEN_WIDTH)
set(QUL_DEFAULT_SCREEN_WIDTH 480)
endif()
if(NOT QUL_DEFAULT_SCREEN_HEIGHT)
set(QUL_DEFAULT_SCREEN_HEIGHT 272)
endif()


 CompilationOptions.cmake  contains compile and link options specific to your platform, such as architecture options and Qt Quick Ultralite specific compile definitions.

For Qt Quick Ultralite, the following definitions must be set in your project:

Definition 描述
 QUL_STATIC_NO_PRELOAD_ASSET_SEGMENT  Assets that are loaded during the Qt Quick Ultralite application execution are added to this section of memory. The name of the section must be defined in the linker script.
 QUL_STATIC_ASSET_SEGMENT  Assets that are preloaded before the Qt Quick Ultralite application execution are added to this section of memory. The name of the section must be defined in the linker script.

These definitions require memory section names to be defined in the platform's linker script. See Linker script setup for instructions on how to setup a linker script for the Qt Quick Ultralite project.

add_compile_definitions(
# Archtitecture specific compile definitions
USE_HAL_DRIVER
)
add_compile_options(
# Archtitecture specific compile options
-mthumb
-mapcs
-mcpu=cortex-m7
-mfloat-abi=hard
-mfpu=fpv5-sp-d16
)
add_compile_definitions(
QUL_STATIC_NO_PRELOAD_ASSET_SEGMENT=AssetDataKeepInFlash
QUL_STATIC_ASSET_SEGMENT=AssetDataPreload
)
add_link_options(
# Archtitecture specific link options
-mthumb
-mfloat-abi=hard
-mfpu=fpv5-sp-d16
-mcpu=cortex-m7
-mapcs
)


For IAR compiler, use the following example as a reference:

add_compile_definitions(
# Archtitecture specific compile definitions
USE_HAL_DRIVER
)
add_compile_options(
# Archtitecture specific compile options
"$<$<COMPILE_LANGUAGE:ASM>:--cpu;Cortex-M7>"
"$<$<COMPILE_LANGUAGE:ASM>:--fpu;VFPv5_D16>"
"$<$<NOT:$<COMPILE_LANGUAGE:ASM>>:--cpu=Cortex-M7>" "$<$<NOT:$<COMPILE_LANGUAGE:ASM>>:--fpu=VFPv5_D16>"
"$<$<NOT:$<COMPILE_LANGUAGE:ASM>>:--endian=little>" "$<$<NOT:$<COMPILE_LANGUAGE:ASM>>:--aapcs=vfp>"
--thumb
)
add_compile_definitions(
QUL_STATIC_NO_PRELOAD_ASSET_SEGMENT=AssetDataKeepInFlash
QUL_STATIC_ASSET_SEGMENT=AssetDataPreload
)
add_link_options(
# Archtitecture specific link options
)

##### Creating the platform kit configuration file

 <YOUR_PLATFORM>.json  file is used to create a platform kit in the Qt Creator IDE.

The JSON file contains an object with values that are used by Qt Creator to create the kit:

 qulVersion  Qt Quick Ultralite version the platform is built against. By default, this is set to  @CMAKE_PROJECT_VERSION@  .
 platform  Name of the platform.
 platformVendor  Name of the platform vendor/manufacturer.
 colorDepths  List of supported color depths for the platform.
 toolchain  Object containing details of the toolchain the platform uses.
 boardSdk  Object containing details of the SDK the platform uses.

 toolchain  attribute contains the following information:

 id  Name of the toolchain.
 versions  List of toolchain versions that are supported.
 cmakeToolchainFile  Location of the toolchain's CMake file.

 boardSdk  attribute contains the following information:

 envVar  Environment variable name pointing to the SDK used in Qt Quick Ultralite.
 versions  List of SDK versions that are supported.

Here is an example JSON file (  example-baremetal.json  ):

{
"qulVersion": "@CMAKE_PROJECT_VERSION@",
"platform": "EXAMPLE-BAREMETAL",
"platformVendor": "VENDOR_NAME",
"colorDepths": [
16
],
"toolchain": {
"id": "armgcc",
"versions": [
"8-2019-q3-update"
],
"cmakeToolchainFile": "lib/cmake/Qul/toolchain/armgcc.cmake"
},
"boardSdk": {
"envVar": "VENDOR_SPECIFIC_SDK_PATH_VARIABLE",
"versions": [
"1.16.0"
]
}
}


Here is the JSON file for the IAR compiler. It has a few differences compared to the previous example:

{
"qulVersion": "@CMAKE_PROJECT_VERSION@",
"platform": "EXAMPLE-BAREMETAL",
"platformVendor": "VENDOR_NAME",
"colorDepths" : [
16
],
"toolchain": {
"id": "iar",
"versions": [
"8.40.1"
],
"cmakeToolchainFile": "lib/cmake/Qul/toolchain/iar.cmake"
},
"boardSdk": {
"envVar": "VENDOR_SPECIFIC_SDK_PATH_VARIABLE",
"versions": [
"1.16.0"
]
}
}

##### 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

 LinkerScriptLoader.cmake  is used by CMake to find the platform's linker script and how to use it in the compiler.

Here is how the  LinkerScriptLoader.cmake  looks for the  example-baremetal  platform:

if(NOT LINKER_SCRIPT)
SET(LINKER_SCRIPT ${CMAKE_CURRENT_LIST_DIR}/example-platform.ld) endif()  LINKER_SCRIPT defines the linker script to use. For more information, see Using a custom toolchain . For IAR compiler, use the following example as a reference: if(NOT LINKER_SCRIPT) SET(LINKER_SCRIPT${CMAKE_CURRENT_LIST_DIR}/example-platform.icf)
endif()


### Creating the configuration file for you 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 文档编制 . You can also use  platform\boards\qt\example-baremetal\CMakeLists.txt  as a basis for your platform's  CMakeLists.txt  .

The following is the  CMakeLists.txt  example-baremetal  platform:

target_sources(QuickUltralitePlatform PRIVATE
examplelayerengine.cpp
platform.cpp
mem.cpp
${PLATFORM_COMMON_SRC_DIR}/singlepointtoucheventdispatcher.cpp # Add platform source files here ) target_include_directories(QuickUltralitePlatform PRIVATE # Add platform specific include directories here ) target_compile_definitions(QuickUltralitePlatform PRIVATE # Insert platform specific compile flags here # e.g. APPLICATION_ADDRESS=0x90000000 )  For IAR compiler, use the following example as a reference: target_sources(QuickUltralitePlatform PRIVATE examplelayerengine.cpp platform.cpp mem-iar.cpp${PLATFORM_COMMON_SRC_DIR}/singlepointtoucheventdispatcher.cpp
# Add platform source files here
)
target_include_directories(QuickUltralitePlatform PRIVATE
# Add platform specific include directories here
)
target_compile_definitions(QuickUltralitePlatform PRIVATE
# Insert platform specific compile flags here
# e.g. APPLICATION_ADDRESS=0x90000000
)


The example  CMakeLists.txt  has two files defined in sources:  platform.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:

1. Create a new file called  ExecutableHook.cmake  under the  platform\boards\<MANUFACTURER_NAME>\<YOUR_PLATFORM>\cmake  目录。
2. 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()


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 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.

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 = 8M /* external sdram memory */
QSPI (rx)                : ORIGIN = 0x90000000, LENGTH = 64M /* external flash */
}


This layout has four regions: FLASH, RAM, SDRAM and QSPI. RAM and SDRAM both have execute, read, and write access. Whereas, FLASH and QSPI are read-only flash memories and thus have only read and execute access.

To get asset separation in your project, Qt Quick Ultralite must know which memory sections are used for asset data:

    AssetDataPreload :
{
. = ALIGN(4);
_preloadable_assetdata_dst_begin = .;
*(AssetDataPreload)
. = ALIGN(4);
_preloadable_assetdata_dst_end = .;
} > SDRAM AT> QSPI
_preloadable_assetdata_src = LOADADDR(AssetDataPreload);
AssetDataKeepInFlash :
{
. = ALIGN(4);
*(AssetDataKeepInFlash)
} > QSPI


In this example, both preloadable asset data and static asset data are kept in the QSPI flash memory region, but preloadable asset data section also reserves space from SDRAM. Both  AssetDataPreload  and  AssetDataKeepInFlash  names can be changed, but they must be consistent with names specified in  platform\boards\<MANUFACTURER_NAME>\<YOUR_PLATFORM>\<YOUR_COMPILER>\CompilationOptions.cmake  .

 _preloadable_assetdata_dst_begin  ,  _preloadable_assetdata_dst_end  ，和  _preloadable_assetdata_src  must also be defined. They are used in the platform code to load the assets from QSPI to SDRAM:

// Preloading assets
extern unsigned char _preloadable_assetdata_src;
extern unsigned char _preloadable_assetdata_dst_begin;
extern unsigned char _preloadable_assetdata_dst_end;
memcpy(&_preloadable_assetdata_dst_begin,
&_preloadable_assetdata_src,
&_preloadable_assetdata_dst_end - &_preloadable_assetdata_dst_begin);


For IAR compilers there need to be some section declarations included

#pragma section = "AssetDataPreload"
#pragma section = "AssetDataPreload_init"
char *_preloadable_assetdata_src = (char *) (__section_begin("AssetDataPreload_init"));
char *_preloadable_assetdata_dst_begin = (char *) (__section_begin("AssetDataPreload"));
char *_preloadable_assetdata_dst_end = (char *) (__section_end("AssetDataPreload"));
memcpy(_preloadable_assetdata_dst_begin,
_preloadable_assetdata_src,
(unsigned) _preloadable_assetdata_dst_end - (unsigned) _preloadable_assetdata_dst_begin);


Make sure to check the example IAR linker script to see how to place these sections in your device memory.

## 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:

1. Add a  <YOUR_COMPILER>.cmake  to  lib\cmake\Qul\toolchain  目录。
2. 创建  <YOUR_COMPILER>  directory under  platform\boards\<MANUFACTURER_NAME>\<YOUR_PLATFORM>\cmake  .
3. Edit CMake configuration files in Qt Quick Ultralite

### Adding  <YOUR_COMPILER>.cmake  to the project

Add the  <YOUR_COMPILER>.cmake  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 描述
 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  LinkerScriptLoader.cmake  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 as  Wall  and  Werror  . 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 for  QuickUltralitePlatform  here.
•  src\CMakeLists.txt  is used to build  QuickUltralite  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  .