Zephyr は、組み込みシステム向けのRTOSです。完全なプリエンプティブ型ティックレスカーネル、協調型およびプリエンプティブ型のスレッド処理、セマフォ、キューを提供します。

Qt Quick Ultralite 既存のZephyr プロジェクトとの統合を容易にするツールを提供しています。Qt Quick Ultralite のZephyr モジュールは、Zephyr のCMake configureステップ中にqmlprojectexporter を実行し、Zephyr ボードをQt Quick Ultralite プラットフォームにマッピングし、生成されたソースコードをZephyr ライブラリとしてビルドに追加するWestモジュールです。このモジュールはKconfigを通じて設定され、Qt Quick Ultralite ターゲットライブラリをビルドするためのwest build-qul-libs コマンドを提供します。

サポートされているアーキテクチャ、プラットフォーム、およびZephyr のバージョン

Qt Quick Ultraliteは以下のハードウェアをサポートしています：

さらに、Qt Quick Ultralite は、Zephyr のホストベースシミュレータボードをサポートしており、このボードではZephyr が開発用ホスト上でアプリケーションとして実行されます：

前提条件

Qt Quick Ultralite のZephyr モジュールを使用するには、以下の前提条件をインストールする必要があります：

• Qt for MCUs 2.12.3
• Qt Quick Ultraliteプラットフォームパッケージ（対応プラットフォームを参照）
• Zephyr 4.4.0
• ターゲット用のツールチェーン:
  • Zephyr SDK 1.0.1
  • native_sim用GNUコンパイラコレクション（GCC）
• CMake 3.21.1 以降
• Ninja 1.10.0 以降
• Python 3.12 以降

ワークフロー

Qt Quick Ultralite アプリケーションを作成およびコンパイルするための全体的なワークフローは、以下の通りです：

新しいアプリケーションの設定

このセクションでは、Qt Quick Ultralite を実行するZephyr アプリケーションの設定について説明します。Qt Quick Ultralite アプリケーションを作成するには、MCU向けドキュメントの「Qt Design Studio 」を参照してください。

Zephyr アプリケーションディレクトリの作成

Qt Quick Ultralite は、Zephyr アプリケーションによって作成される独自のZephyr スレッド内で実行されます。このスレッドは、Qul::Application::exec()を通じてQt Quick Ultralite イベントループを実行し、独立して動作します。Zephyr アプリケーションの残りの部分は、これと並行して実行されます。スレッドを作成するアプリケーションは、CMakeLists.txt ファイル、prj.conf ファイル、およびアプリケーションのソースコードで構成されています。

westワークスペース用のディレクトリを作成し、その下にアプリケーションディレクトリapp と、そのサブディレクトリとしてsrc を作成します：

mkdir myproject
cd myproject
mkdir -p app/src

mkdir myproject
cd myproject
mkdir app\src

Qt Quick Ultralite の取得Zephyr モジュールリポジトリ

Qt Quick Ultralite Zephyr モジュールは、Qt Quick Ultralite のインストールに含まれるgitバンドルファイルとして配布されています：

<QT_INSTALL>/QtMCUs/2.12.3/platform/boards/zephyr/qtultralight-zephyr-module.bundle

このバンドルを使用してモジュールリポジトリのローカルコピーを作成し、そのコピーを West ワークスペースからアクセス可能な Git サーバー上で利用可能にしてください:

git clone --origin bundle <path/to/qtultralight-zephyr-module.bundle> qtultralight-zephyr-module
cd qtultralight-zephyr-module
git branch -m main
git remote add origin <your-git-server-url>/qtultralight.git
git push origin main

次の手順で作成される `app/west.yml` 内の `qt ` リモートに対して、`url-base ` の値と同じサーバー URL を使用してください。

各Qt Quick Ultraliteリリースには、更新されたバンドルが含まれています。新しいQt Quick Ultraliteバージョンに移行するには、そのリリースのバンドルを使用してこれらの手順を繰り返し、Gitサーバー上のコピーを更新してください。その後、既存のWestワークスペースでwest update を実行して、新しいコミットを取得してください。

app/west.yml の作成

これらの手順では、west マニフェストをアプリケーションディレクトリ内に保持するため、app もマニフェストリポジトリとなります。アプリケーションとは別のマニフェストリポジトリを使用する場合も、動作は同様です。west がサポートするワークスペースのトポロジについては、「west ワークスペース」を参照してください。

app/west.yml に west マニフェストを作成します。qt リモートに対して、url-base を、前の手順でQt Quick Ultralite Zephyr モジュールリポジトリをプッシュした Git サーバーの URL に設定します。Qt Quick Ultralite Zephyr モジュールをその中のプロジェクトとして追加し、import: true を指定して、west がモジュール自身のマニフェストも読み込めるようにします。このマニフェストには、build-qul-libs 拡張コマンドが宣言されています:

manifest:
  remotes:
    - name: zephyrproject-rtos
      url-base: https://github.com/zephyrproject-rtos
    - name: qt
      url-base: https://your.git.server/path

  projects:
    - name: zephyr
      remote: zephyrproject-rtos
      revision: v4.4-branch
      import: true

    - name: qtultralight
      remote: qt
      repo-path: qtultralight.git
      revision: main
      path: qtultralight
      import: true

  self:
    path: app

qtultralight プロジェクトが指すリポジトリは、薄いラッパーです。そこにはZephyr の統合部分のみが含まれています。具体的には、Kconfig定義、Zephyr のCMakeファイル、およびwest build-qul-libs コマンドです。Qt Quick Ultralite 自体はこれに含まれていないため、west update はラッパーのみをクローンします。

qmlprojectexporter などのホストツール、プラットフォームのソースコード、およびターゲットライブラリは、west ワークスペースの外に保持されているQt Quick の Ultralite インストールから取得されます。このモジュールは、QUL_ROOT を通じてそのインストールを特定します。

ワークスペースの初期化と更新

west init -l app
west update

app/CMakeLists.txt の作成

app/ ディレクトリに、アプリケーションのソースを列挙した簡単な `CMakeLists.txt ` ファイルを作成します:

cmake_minimum_required(VERSION 3.20.0)
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
project(myapp)

target_sources(app PRIVATE src/qul_main.cpp)

生成されたプロジェクトには、プラットフォーム移植版のzephyr-linker-sources.cmake も含まれており、これにより、Zephyr で生成されたリンカースクリプトにQt Quick Ultralite のリンカーセクションが追加されます。

app/prj.conf の作成

app/prj.conf を作成して、モジュールを有効にし、qmlproject ファイルを指定します。

CONFIG_QUL=y
CONFIG_QUL_QMLPROJECT_FILE="path/to/your/qul_application.qmlproject"

CONFIG_QUL_QMLPROJECT_FILE 絶対パス、アプリケーションディレクトリを基準とした相対パス、または~ で始まるパスを指定できます。

これら2つのオプションが最小限の設定となります。Qt Quick Ultralite 固有の Kconfig 値の完全なリストについては、Kconfig リファレンスを参照してください。

app/src/qul_main.cpp の作成

app/src/qul_main.cpp 内にアプリケーションのエントリポイントを作成します。このソースファイルは、Qt Quick Ultraliteを実行するスレッドを提供します。QMLルートアイテムのヘッダーは、ビルド時に.qmlproject ファイルから生成され、自動的にインクルードパスに追加されます：

#include "MainScreen.h"

#include <qul/application.h>
#include <qul/qul.h>
#include <zephyr/kernel.h>

#define QUL_THREAD_STACK_SIZE 16384
#define QUL_THREAD_PRIORITY   5

static void qul_thread_entry(void *, void *, void *)
{
    Qul::initHardware();
    Qul::initPlatform();

    Qul::Application app;
    static MainScreen item;
    app.setRootItem(&item);
    app.exec();
}

K_THREAD_DEFINE(qul_tid, QUL_THREAD_STACK_SIZE,
                qul_thread_entry, NULL, NULL, NULL,
                QUL_THREAD_PRIORITY, 0, 0);

K_THREAD_DEFINE 起動時にZephyr スレッドを作成します。このスレッドのエントリポイントは、Qt Quick Ultralite のイベントループを開始する前に、ハードウェアとプラットフォームを初期化します。

QUL_ROOTの設定

Qt Quick Ultralite のZephyr モジュールが動作するには、Qt for MCUs のインストールが必要です。モジュールがホストツール、プラットフォームのソース、およびライブラリを検出できるように、環境変数QUL_ROOT にインストールディレクトリを設定してください:

export QUL_ROOT=$HOME/Qt/QtMCUs/2.12.3

set QUL_ROOT=C:\Qt\QtMCUs\2.12.3

また、-- の後に、west build コマンドにQUL_ROOT を引数として渡すことで、 を設定することもできます：

west build -b <board> app -- -DQUL_ROOT=$HOME/Qt/QtMCUs/2.12.3

west build -b <board> app -- -DQUL_ROOT=C:\Qt\QtMCUs\2.12.3

設定

Qt Quick Ultralite Zephyr モジュールは、Qt Quick Ultralite をZephyr アプリケーションに組み込む方法を設定するKconfigオプションを追加します。これらのオプションは、アプリケーションのprj.conf ファイル内で、または対話型のKconfigインターフェースを通じて設定します。

west build -b <board> app -t menuconfig

ここで、<board> はZephyr ボードターゲット、-b は--board の短縮形です。menuconfig ターゲットは CMake の configure ステップを実行しますが、これにはボードターゲットが必要です。ビルドディレクトリが一度作成されると、west は CMake キャッシュからボードを再利用するため、-b <board> を省略できます。

Qt Quick のUltraliteオプションは、Modules > qtultralight にあります。変更内容はbuild/zephyr/.config に保存され、次回のwest build 実行時に反映されます。オプションの完全な一覧については、Kconfigリファレンスを参照してください。

Qt Quick Ultralite アプリケーション自体の設定は、その.qmlproject ファイルおよびプラットフォームのBoardDefaults_*.qmlprojectconfig ファイルで行われます。詳細は、QmlProject マニュアルおよび 「プラットフォームのデフォルト変数の定義」を参照してください。このモジュールは、CMake 変数および環境変数を通じて、Qt Quick Ultralite のインストール先とプラットフォームのソースを特定します。詳細は、CMake 変数リファレンスおよび環境変数リファレンスを参照してください。

ビルド

デフォルトでは、Qt Quick Ultraliteはインストール先の事前ビルド済みライブラリを使用します。ライブラリを独自にビルドするには、「Qt Quick Ultraliteライブラリのビルド」を参照してください。

ターゲットボードを指定してwest build を実行し、アプリケーションをビルドします:

west build -b <board> app

ここで、<board> はZephyr ボードターゲットです。使用するボードターゲットについては、「サポートされているアーキテクチャ、プラットフォーム、およびZephyr のバージョン」に記載されているボード固有のページを参照してください。

このモジュールは、QUL_ZEPHYR_BOARDS 変数を通じて、ボードターゲットをQt Quick Ultraliteプラットフォームにマッピングします。各プラットフォームポートは、そのzephyr-boards.cmake ファイル内でサポートするボードターゲットを列挙しており、モジュールは、そのリストにボードターゲットがそのまま記載されているポートを選択します。

変更後の再ビルド

Qt Quick Ultralite アプリケーションのQMLファイルや.qmlproject ファイルを変更した場合は、Zephyr プロジェクトを再ビルドするだけで済みます。qmlprojectexporter は、変更が検出されると自動的にQt Quick Ultralite アプリケーションを再エクスポートします。

フラッシュ

ハードウェアボードの場合は、west を使用してビルド済みのアプリケーションをフラッシュします:

west flash

Qt Quick Ultralite ライブラリのビルド

デフォルトでは、Qt Quick Ultraliteはインストール時の事前ビルド済みライブラリを使用します。これらはMinSizeRel またはRelease 構成でビルドされています。独自のライブラリをビルドするには、west build-qul-libs を実行します。以下の例は、Debug 構成でライブラリをビルドするものです：

west build-qul-libs --board <board> --build-type Debug

ここで、<board> はZephyr ボードターゲットであり、west build と同じ値です。

このコマンドは、Qt Quick のUltraliteプラットフォームおよびコアライブラリをビルドし、それらを<build-dir>/qul_install にインストールします。アプリケーション自体はビルドしません。ライブラリのインストール後、このコマンドはZephyr のビルドディレクトリを再構成し、次回のwest build で新しいライブラリが読み込まれるようにします。

このコマンドでは、以下のオプションがサポートされています:

ビルドディレクトリは、ライブラリのビルドと同じボード用に設定されていることが想定されています。--board がビルドディレクトリに記録されているボードと一致しない場合、コマンドはエラーで停止します。

DeviceLink

DeviceLinkは、デバイスとホスト間でタッチ、パフォーマンス、およびログデータを交換します。アプリケーションのprj.conf でこれを有効にします：

CONFIG_QUL_DEVICELINK=y

その後、モジュールはプラットフォームポートの DeviceLink デバイスツリーオーバーレイと Kconfig フラグメントを適用し、一致するプラットフォームメタデータを選択します。DeviceLink はコンパイル時の機能であるため、オプションを変更した後に west build-qul-libs を実行してください。

詳細については、「DeviceLink 通信の移植」を参照してください。

Kconfig リファレンス

CONFIG_QUL が有効になっている場合、以下のオプションが利用可能です。アプリケーションの `prj.conf ` または `west build app -t menuconfig` を通じて設定してください。

CMake 変数リファレンス

-- の実行後に、これらの変数をwest build に渡し、例えばwest build -b <board> app -- -DQUL_ROOT=<path/to/qul> のように指定します。

環境変数のリファレンス

Qt Quick Ultralite をZephyr プラットフォームに移植する

『Qt Quick Ultralite Platform Porting Guide』に従うことで、Qt Quick Ultralite をZephyr プラットフォームに移植できます。リファレンスポートでは、以下の部分がZephyr のAPIを使用して実装されています：

• currentTimestamp() はk_uptime_get() を呼び出します。
• タッチ操作のサポートは、Zephyr の入力APIを使用して実現されています。
• Qt Quick Ultraliteキューは、Zephyr メッセージキューを使用しています。
• セマフォは、Qt Quick のUltraliteスレッドの動作を一時停止および再開するために使用されます。
• qul_malloc(),qul_realloc(), およびqul_free() は、それぞれk_malloc(),k_realloc(),k_free() を呼び出すため、Qt Quick Ultralite での動的割り当てはZephyr カーネルヒープから行われます。UI ツリー、画像バッファ、フォントデータなど、アプリケーションが行う割り当てをカバーできるよう、CONFIG_HEAP_MEM_POOL_SIZE を使用してそのヒープのサイズを調整してください。アロケータ API については、「Qt Quick Ultralite プラットフォーム抽象化におけるメモリ割り当て」を参照してください。
• ディスプレイ割り込みは、Zephyr を使用して設定および有効化されます：

  void setInterruptPriorities()
  {
      IRQ_CONNECT(LCDIF_IRQn, 3, displayIRQHandler, NULL, 0);
      irq_enable(LCDIF_IRQn);
  }

• LCD 画面のピンマルチプレクシングは、Zephyr のピン制御 APIを使用して初期化されます。

  #define LCDIF_DEV DT_NODELABEL(lcdif)
  
  void initializeLcdPinmux()
  {
      PINCTRL_DT_DEFINE(LCDIF_DEV);
  
      pinctrl_apply_state(PINCTRL_DT_DEV_CONFIG_GET(LCDIF_DEV), PINCTRL_STATE_DEFAULT);
  }

Zephyr Kconfig オプション

このモジュールと併用されるプラットフォーム・ポートは、Qt Quick Ultralite がターゲット上で必要とするZephyr Kconfig オプションを、そのqul_module.conf ファイル内に提供します。モジュールは、Kconfig が実行される前にそのファイルをEXTRA_CONF_FILE に追加し、アプリケーションのビルドにオプションを適用します。

リファレンスポートで必要なオプションについては、ボードページの「必要な Kconfig オプション」を参照してください。