Generatorユーザ・ガイド
X-CUBE-TOUCHGFXの一部であるTouchGFX Generatorは、CubeMXの追加ソフトウェア・コンポーネントで、開発者がハードウェア・プラットフォーム上でTouchGFXを実行するための設定を行うのを支援するものです。 既存のCubeMXの設定とユーザ入力に基づいて、TouchGFX Generatorは機能するTouchGFXアプリケーションの設定に必要なファイルを生成します。 ここには、TouchGFX HAL、TouchGFX OSAL、およびTouchGFXの設定ファイルが含まれています。
CubeMXを介してコードを生成すると、TouchGFX DesignerからTouchGFXプロジェクトを開けるようになり、ここでUIを開発できます。 TouchGFX Designerは、追加生成されたコードのファイルを、CubeMXでプロジェクト用に設定されたターゲットのIDEプロジェクトに自動的に追加します。
TouchGFX Generatorの有効化
次の図は、TouchGFX Generatorが[Additional Software]カテゴリの下ですでに有効化された状態のプロジェクトを示しています。 ユーザは、X-CUBEから[Additional Software]ボタンを押すことで、追加機能にアクセスできます。
次の図は、プロジェクトに対してTouchGFX Generatorを有効化する方法を示しています。
生成されるコードのアーキテクチャ
TouchGFX Generatorの機能の説明の前に、生成されるコードのアーキテクチャと、開発者がそれを使用して設定や動作をカスタマイズする方法について理解することが重要です。
CubeMXで生成するファイル内のユーザ記述のコードは、CubeMX(Cコード) で生成されるコード全体に明示的に配置されたユーザ・コード・セクションを使用することで保護されます。TouchGFX Generator(C++コード)で生成されるコードでは、この柔軟性が保持されています。
[Additional Software]でTouchGFX Generatorを追加し、有効化すると、CubeMXは常にそのプロジェクトにTouchGFXフォルダを作成します。 このフォルダには設定に関わらず常に同じファイルが含まれますが、ファイルの内容はCubeMXおよびユーザ設定に応じて変わります。
次のリストは、TouchGFX Generatorが有効化されたCubeMXプロジェクトの内容の概要を示しており、特にTouchGFX関連ファイルが強調されています。 リストの後の表は、最も重要なエントリの役割を概説しています。
TouchGFX フォルダ
│ .mxproject
│ myproject.ioc
├───Core
├───Drivers
├───EWARM
├───Middlewares
└───TouchGFX
│ ApplicationTemplate.touchgfx.part
├───App
│ app_touchgfx.c
│ app_touchgfx.h
└───target
│ STM32TouchController.cpp
│ STM32TouchController.hpp
│ TouchGFXGPIO.cpp
│ TouchGFXHAL.cpp
│ TouchGFXHAL.hpp
│
└───generated
OSWrappers.cpp
TouchGFXConfiguration.cpp
TouchGFXGeneratedHAL.cpp
TouchGFXGeneratedHAL.hpp
フォルダ | 役割 |
---|---|
myproject.ioc | CubeMXプロジェクト・ファイル |
Core | main.c と起動コード |
Drivers | CMSISとマイクロコントローラ・ファミリのドライバ |
EWARM | IDEプロジェクト・フォルダ。 EWARM、MDK-ARM、STM32CubeIDEのいずれか |
Middlewares | TouchGFXライブラリ / ヘッダファイルと、サードパーティ・ソフトウェア(FreeRTOSなど)が含まれます。 |
ApplicationTemplate.touchgfx.part | .partファイルはCubeMXによって、TouchGFX Designerプロジェクトに関連する情報(画面の寸法やビット深度など)で更新されます。 |
App | X-CUBEのCubeMXに対するインタフェース。 app_touchgfx.c には、関数MX_TouchGFX_Process(void) および MX_TouchGFX_Init(void) の定義が含まれます。これらの関数はTouchGFXを初期化してメイン・ループを開始するために使用されます。 |
target/generated | このサブフォルダには、設定変更時にCubeMXによって上書きされる読出し専用ファイルが含まれます。 TouchGFXGeneratedHAL.cpp はTouchGFXクラスHAL のサブクラスで、CubeMXが現在の設定に基づいて生成することのできるコードが含まれます。 OSWrappers.cpp OSAL)にはTouchGFXエンジンとの同期に必要な関数が含まれます。最後にTouchGFXConfiguration.cpp には、TouchGFXの構築および設定のためのコードが含まれます(HALを含む)。 |
target | HALの動作を拡張したりCubeMXによって生成された設定をオーバーライドしたりするためにユーザが変更できるファイルの大部分が含まれています。 STM32TouchController.cpp には、空のタッチ・コントローラ・インタフェースが含まれます。 TouchGFXHAL.cpp は、TouchGFXGeneratedHAL のサブクラスTouchGFXHAL ,を定義します。 |
TouchGFXConfiguration.cpp
にはHALを構築する関数とTouchGFXのメイン・ループを開始する関数が含まれることを把握しておくことが重要です。 追加設定は、編集可能なユーザクラスTouchGFXHAL
にて行うことができます。 HALの一般的なアーキテクチャは次のようになります。
機能の概要
TouchGFX Generatorを有効にすると、ユーザ・インタフェースには次の3つのグループが表示されます。
- Dependencies - このグループには依存関係、警告、または設定内の具体的なエラーに関する開発者への通知が含まれます。 エントリが存在しない場合、このグループは非表示になります。
- Display - このグループにはディスプレイに関連する設定(インタフェース、フレームバッファのビット深度、幅、高さなど)が含まれます。 これらの設定は、TouchGFXプロジェクトのキャンバスのサイズや、アセット用に生成されるコードに直接影響します。
- Driver - このグループでは、アプリケーション、グラフィック・アクセラレーション、RTOSのティック・ソースに関連する多くの既製のドライバに対してユーザがオプトインできます。 CubeMXはFreeRTOS(CMSIS RTOS v1およびv2)の設定をサポートしているため、TouchGFX Generatorはこれらの各オプションに対してドライバを提供します。
Display
Display グループには、ディスプレイに関連する設定(インタフェース、寸法、バッファリング戦略など)が含まれます。
インタフェースと寸法
現在、STM32マイクロコントローラでは、次に示すような複数のディスプレイ・インタフェースを使用できます。
- パラレルRGB
- MIPI DSI
- FMC
- SPI
LTDC搭載マイクロコントローラの場合、TouchGFX Generatorは、フレームバッファを接続されたディスプレイに転送するためのドライバを生成できます。 DSI、FMC、およびSPIインタフェースのドライバは、開発者自身で実装する必要があります。
Further reading
Buffering Strategies
TouchGFX Generatorを介して、次のフレームバッファ戦略を設定できます。
- Single Buffer- アプリケーション・フレームバッファを1つだけ使用します。 パフォーマンスが制限される可能性がありますが、メモリの使用量は少なくて済みます。 [Buffer Location]設定で使用して、内部RAMに配置できます。 さらに最適化するには、ディスプレイ・コントローラによって現在処理されているラインを返す関数をユーザが定義できます。 この方法はフレームワークによって使用され、このフレームですでにディスプレイに転送済みのメモリへの更新ができるようになります。
- Double Buffer - 2つのフレームバッファを使用します。 通常、多くのメモリを必要としますが、パフォーマンスが向上します。
- Partial Buffer- 1つ以上のユーザ定義のメモリ領域をフレームバッファとして使用します。 この戦略は外部RAMに頼らないが、ディスプレイのフレームバッファ全体では使用可能なメモリ量を超える可能性がある場合の低コストのソリューションをターゲットにしています。
シングル・バッファとダブル・バッファの場合、ユーザは[Buffer Location]設定で次のオプションを使用して場所を設定できます。
- By Allocation - リンカがリンカ・スクリプトに従ってフレームバッファのメモリを配置できます。 デフォルトは内部RAMです。
- By Address - ユーザが1つ(シングル)または2つ(ダブル)のフレームバッファ・アドレスを定義できます。
パーシャル・バッファ戦略では、ユーザは以下のパラメータを定義できます。
- ブロック数(常に内部RAMに配置される)
- ブロック・サイズ(バイト)
パーシャル・バッファ戦略に関する中心的な概念を理解するには、パーシャル・フレームバッファを使用してメモリ要件を軽減する方法に関する専門の記事を参照してください。 この記事はパーシャル・フレームバッファを実現する方法を概念的に示したものなので、この記事に示すコードはTouchGFX Generatorによって生成されるコードと少し異なっています。 これらの戦略で生成されるコードの具体例については、「フレームバッファ戦略」を参照してください。
Driver
[Driver]セクションでは、TouchGFX ALのさまざまな役割に対応するドライバを開発者が選択できます。
Application Tick Source
アプリケーションのティック・ソースは、アプリケーションを前進させる方法を定義します。 開発者は以下のオプションを使用できます。
- LTDC - [Display]グループの[Interface]で[LTDC]を選択した場合、[Application Tick Source]を[LTDC]にできます。 つまり、TouchGFX Generatorが
TouchGFXGeneratedHAL
クラスにドライバ関数(LTDC割込みハンドラ)をインストールし、それがOSWrappers::signalVSync()
.を呼び出してアプリケーションを前進させます。 - Custom - この場合、
OSWrappers::signalVSync()
を繰り返し呼び出すことでアプリケーションを前進させるハンドラを、開発者が実装する必要があります。
Graphics Accelerator
グラフィック・アクセラレーションに関して、開発者には次の3つのオプションがあります。
- None- アプリケーションはCPUのみを使用してフレームをレンダリングします。
- Chrom-ART (DMA2D) - アプリケーションは可能であればChrom-ART機能を使用してピクセルの移動やブレンドを行い、CPUサイクルを解放します。 TouchGFX Generatorによってドライバがインストールされるので、開発者によるアクションは必要ありません。
TouchGFX Generatorから提供されるChrom-ART(DMA2D)ドライバは、TransferCompleteInterruptの受信方法として次の2つをサポートしています。
- TM32Cube HALドライバを使用して、dma2dハンドラにコールバック関数
hdma2d.XferCpltCallback
を登録する。 DMA2D_IRQHandler()
割込みハンドラを直接使用する。
この2つの方法を切り替えるには、DMA2D IP用のCubeMXのNVIC設定で、DMA2Dグローバル割込みを有効化 / 無効化します。 グローバル割込みを有効化するとオプション1のコードが生成され、グローバル割込みを無効化するとオプション2のコードが生成されます。
Note
Real-Time Operating System
開発者はTouchGFXで任意のRTOSを使用できます(OS無しも含む)。 「抽象化レイヤ・アーキテクチャ」で説明したように、TouchGFXエンジンはインタフェースを使用して、ユーザが選択したRTOSと、メイン・イベント・ループおよびフレームバッファのアクセスを同期させます。OSWrappers
FreeRTOSはCubeMXおよびTouchGFX Generator内から直接設定可能で、タスク定義とTouchGFX RTOSドライバの両方のユーザ生成のコードを付与します TouchGFX GeneratorではCMSIS V1およびCMSIS V2準拠のRTOSドライバを生成可能で、これは任意のCMSIS準拠のRTOSで機能します。 この場合、開発者はCubeMXを使用してタスク定義のコードを生成できなくなり、ユーザ・コードでこれを行う必要が生じます。
次の図は、TouchGFX Generatorを通して使用可能なオプションを示しています。
次の関数を呼び出すと、TouchGFXのメイン・ループに入ります。
void MX_TouchGFX_Process(void);
開発者はTouchGFXアプリケーションを実行したいタスクのタスク・ハンドラ内で、この関数を呼び出す必要があります。 次の例は、ユーザがCubeMXからDefaultTask
という名前のFreeRTOSタスクを設定した場合に、 MX_TouchGFX_Process()
を呼び出して、このタスク・ハンドラのユーザ・コード・セクションでTouchGFXを開始する方法を示しています。
void StartDefaultTask(void *argument)
{
/* USER CODE BEGIN 5 */
MX_TouchGFX_Process();
/* USER CODE END 5 */
}
FreeRTOSを有効にすると、CubeMXはスケジューラを起動する osKernelStart();
の呼び出しも生成します。
その他のCMSIS準拠OS
CubeMXが提供可能なOS(FreeRTOS)以外のCMSIS準拠OSを必要とする開発者は、RTOSの設定とタスク定義を手動で行う必要があります。 一般的には、以下の手動ステップを行う必要があります。
- RTOSを設定する。
- TouchGFXを実行するためのタスクを定義する(
MX_TouchGFX_Process
)。 - スケジューラを起動する。
ここでは、 Azure RTOS. 向けにステップ2と3を実行する方法の例を示します。 CubeMXはこの設定の支援ができないので、コードの上書きを防ぐため、提供されたユーザ・コード・セクション内ですべてを設定する必要があります。 以下のコードは、GUIタスク定義の疑似コードを示しています。 一般に、CubeMXで生成されていないコードについては、main.c
.ファイル全体に点在するユーザ・コード・セクション内に配置する必要があります。
/* BEGIN USER CODE SECTION */
#include "tx_api.h"
#define GUI_THREAD_STACK_SIZE 1024
TX_THREAD gui_thread;
void gui_thread_entry(ULONG thread_input); //Thread prototype
/* END USER CODE SECTION */
int main()
{
/* BEGIN USER CODE SECTION - Choose an appropriate one from main.c */
/* Allocate the stack for gui thread */
tx_byte_allocate(...);
/* Create the gui thread. */
tx_thread_create(&gui_thread, "GUI Thread", gui_thread_entry, 0,
pointer, GUI_TASK_STACK_SIZE,
1, 1, TX_NO_TIME_SLICE, TX_AUTO_START);
/* END USER CODE SECTION*/
MX_TouchGFX_Process
を呼び出して、タスク・ハンドラ内で TouchGFXエンジンのメイン・ループを開始します。
/* BEGIN USER CODE SECTION */
void gui_thread_entry(ULONG thread_input)
{
MX_TouchGFX_Process();
}
/* END USER CODE SECTION*/
スケジューラを起動して、GUIタスクとTouchGFXアプリケーションを起動します。
/* BEGIN USER CODE SECTION */
tx_kernel_enter();
/* END USER CODE SECTION*/
Additional features
External Data Reader
RGB565フレームバッファ・ピクセル・フォーマットでは、touchgfxは、いわゆるデータ・リーダのインタフェースをサポートしています。これにより開発者は、メモリ内で追加バッファが必要となるキャッシュを行うのではなく、メモリマップされないシリアルFlashから直接データを読み出せます。 データ・リーダを実装して、メモリマップされないFlashチップからアプリケーション・アセットを取得する方法の例については、シリアルFlashの記事を参照してください。
通常、データ・リーダのオプションは、追加バッファ用に十分なメモリを備えていない低コストのソリューション(STM32G0など)で使用されます。 DMA2Dが有効である場合、これは有効化できません。
フレームバッファのピクセル・フォーマットとしてRGB565を選択すると、[Additional Features]グループが使用可能になります。
開発者は以下の設定を行うことができます。
- External Data Reader: この機能を有効化または無効化します。 有効化すると、TouchGFXは生成済みのインタフェースを介してアセットのデータを直接取得します。 無効化した場合は、開発者がメモリ内のバッファに画像をキャッシュする必要があります。
- External Data Reader: Line Buffer Size: 画像またはテキストをフレームバッファにブレンドするための2つのバッファを作成します。 ARGB8888ピクセル・フォーマットでフル・サイズの画像をサポートするためにデフォルト値は、一画面の幅 x 4バイトです。
- External Data Reader: Minimum DMA transfer size: DMA転送を開始するために最小限必要なバイト数を設定します。 これより少ないバイト数が要求された場合、DMAは使用されません。
[External Data Reader] を有効にしてコードを生成すると、メモリマップされないFlashからアセットを直接取得できるように以下の追加ファイルが作成されます。
TouchGFX/target/generated/TouchGFXGeneratedDataReader.cpp
TouchGFX/target/generated/TouchGFXGeneratedDataReader.hpp
TouchGFX/target/TouchGFXDataReader.cpp
TouchGFX/target/TouchGFXDataReader.hpp
通常通り、TouchGFX Generatorによって生成されたコードに対して、TouchGFXGeneratedDataReader
は読出し専用であり、ユーザの変更は TouchGFXDataReader
クラス内で行う必要があります。 TouchGFXGeneratedDataReader
のタイプはtouchgfx::FlashDataReader
.です。
以下のファイルが変更され、DataReader
を使用するようにTouchGFX HALが設定されます。
TouchGFX/target/generated/TouchGFXConfiguration.cpp
TouchGFX/target/generated/TouchGFXGeneratedHAL.cpp
TouchGFX/target/generated/TouchGFXGeneratedHAL.hpp
Note
8bitLTDCカラー・ルックアップ・テーブル
フレームバッファをL8フォーマットで読み出すようにLTDCが設定されており、TouchGFXが ABRG2222、ARGB222、BGRA2222、RGBA2222のいずれかでレンダリングする場合、TouchGFX Generatorは、TouchGFXHAL::initialize()
の実行時にLTDCにロードされるCLUTを提供します。 LTDCおよびCLUTの使用方法の詳細については、STM32マイクロコントローラのリファレンス・マニュアルを参照してください。
生成されるプロジェクト
CubeMXでGenerate Codeボタンを使用してコードを生成する場合、TouchGFXは(少なくとも) 以下のIDEで動作します。
- EWARM
- MDK-ARM
- STM32CubeIDE
最適なプロジェクト構造を得るために、プロジェクト生成では以下のオプションを選択します。
- [Application structure]:[Advanced]
- [Generate under root]無効化(STM32CubeIDEのみ)
最適なプロジェクト構造を得るために、プロジェクト生成では以下のオプションを選択します。
- [Application structure]:[Advanced]
- [Generate under root]無効化(STM32CubeIDEのみ)
- App フォルダには、TouchGFXを初期化し、起動するコードが含まれています。
- targetフォルダには、読出し専用の生成済みコード(generated/内)と、変更可能なユーザ・クラス(
STM32TouchController.cpp
、TouchGFXGPIO.cpp
およびTouchGFXHAL.cpp
が含まれています。 - .partファイルは、TouchGFXヘッダ・ファイルとライブラリを完備した完全なTouchGFXプロジェクトを作成するために、TouchGFX Designerを使用して開かれます。partファイルにはピクセル・フォーマットやDesignerがTouchGFXアプリケーション・コードを生成するときに使用するキャンバスの寸法などの関連するアプリケーション情報が含まれています。
TouchGFX Designerプロジェクト
以下のコードは、 「生成されるコードのアーキテクチャ」セクションで説明した.part
ファイルの内容例を示しています。 下記の生成後コマンドでは、TouchGFX Designerで新しいファイル(新しい画面やアセットなど)が作成されると、CubeMXで選択されたプロジェクト(EWARMなど)が更新されます。
{
"Application": {
"Name": "my_project",
"TouchGfxPath": "../Middlewares/ST/touchgfx",
"AvailableColorDepths": [ 16 ],
"AvailableLCDs":
{
"16": "LCD16bpp"
},
"AvailableResolutions" :
[
{
"Width": 320,
"Height": 240
}
],
"PostGenerateTargetCommand" : "touchgfx update_project --project-file=../my_project.ioc --platform=m7"
},
"Version": "4.13.0"
}
TouchGFX Designerで.part ファイルを開くと、開発者には、具体的なUIをロードするのか、空のテンプレートから開始するのかを選択するオプションが表示されます。
TouchGFX Designerで[Generate Code]を押すと、TouchGFXフォルダの構造は以下のようになります。 下の画像はTouchGFXフォルダ構造の具体例を示しており、生成後の新しいファイルやフォルダをハイライト表示しています。
TouchGFXは、CubeMXの.iocファイルから選択されたIDEを検出し(STM32CubeIDE、EWARM、MDK-ARMの場合)、画面の定義や画像およびフォント・アセットなどの新しく生成されたファイルでプロジェクト・ファイルを更新します。
この時点で開発者は、CubeMX、TouchGFX Designer、およびツールチェーン / IDEで以下のように交互に作業できるようになります。
- CubeMXでIDEプロジェクトのドライバを更新する。
- CubeMXはDesignerで即座に選択したUI関連の変更で、TouchGFX の.partファイルを更新する。
- CubeMXはTouchGFXが特定のプラットフォーム上で動作するために必要なTouchGFX Generatorの設定に基づいて、HALコード(TouchGFX/target/generated/)を生成する。
- TouchGFX Designerは生成されたコードでプロジェクトを更新する。
生成された動作の変更
HALはクラス階層を持つので、CubeMXによって生成されたHALの設定や動作をユーザがオーバーライドできることに留意してください。 以下の例では、開発者が initialize
関数を変更することで、TouchGFXの追加設定や、TouchGFXGeneratedHAL
. の既存の設定の変更が可能です。
TouchGFXHAL.cpp
void TouchGFXHAL::initialize()
{
// Calling parent implementation of initialize().
//
// To overwrite the generated implementation, omit call to parent function
// and implemented needed functionality here.
// Please note, HAL::initialize() must be called to initialize the framework.
TouchGFXGeneratedHAL::initialize();
//Overriding configurations
hal.lockDMAToFrontPorch(true);
hal.setFingerSize(4);
hal....
}
プロジェクトのアップグレード
TouchGFX Generatorのパラメータは.iocファイル(CubeMXプロジェクト)に格納されます。 TouchGFX Generatorの新バージョンがリリースされると、旧バージョンのパラメータが新バージョンと互換性を持たないために移行が必要になる可能性があります。
CubeMXはX-CUBEバージョン間のアップグレードをサポートしていないため、[Generate Code]が押されると、.touchgfx
ファイルの PostGenerateTargetCommand
セクション内の以下のコマンドによってTouchGFX Designerで自動的にアップグレードが実行されます。
.touchgfx
"PostGenerateTargetCommand" : "touchgfx update_project --project-file=../upgrade.ioc --platform=m7"
コマンドによって.ioc
ファイルが読み出され、現在のバージョンのX-CUBE-TOUCHGFXに合うようにパラメータが更新されます。 次の例は、X-CUBE-TOUCHGFX 4.13.0で作成された.iocファイルで、スクリプト(X-CUBE-TOUCHGFX 4.14.0)を手動で実行する方法を示しています。
STM32F746 DISCOアプリケーション・テンプレートを使用した4.13.0から4.14.0へのアップグレード例
$ touchgfx update_project --project-file=../STM32F746G_DISCO.ioc
TouchGFX Generator 4.13.0 found
Creating backup of ../STM32F746G_DISCO.ioc as ../backup_STM32F746G_DISCO.ioc
Performing upgrade 4.13.0 -> 4.14.0 ... OK
更新されたプロジェクトをCubeMXで開くと、.iocファイルで示されたバージョンのX-CUBE-TOUCHGFXをインストールするように求められます(まだインストールしていない場合)。 [Download now]をクリックすると、X-Cube-TouchGFX-4.14.0のダウンロードとインストールが行われます。
アップグレード・プロセスの実行時、TouchGFX Generatorの設定はすべて保持され、.iocファイルのバックアップは先頭にbackup_
が付いた状態で、元のファイルと同じ場所に配置されます