ビルドシステムと設定¶

FreeRTOS アプリケーションは、make が CMake を駆動してビルドします。アプリケーションの .config ファイルにはすべての CONFIG_* 設定が並んでおり、ビルド時にこれが C ヘッダー autoconf.h に変換され、コンパイルするコンポーネントの選択にも使われます。このページではその流れと Reef 用構成のビルド方法を説明します。Zephyr は west でビルドします。Zephyr RTOS を参照してください。

ビルドの流れ¶

flowchart LR
  A[".config または defconfig_*"] --> B["project.build（make）"]
  B --> C["CMake の構成<br/>autoconf.h を生成"]
  C --> D["コンパイルとリンク<br/>make -j4"]
  D --> E["&lt;app&gt;_IPRO7.elf"]
  E --> F["&lt;app&gt;_IPRO7.bin"]

コマンドはすべて SDK のルートディレクトリで実行します。

make -C apps/platform/ipro7ai_reef_demo          # 出荷時ファームウェアをビルド
make -C apps/platform/ipro7ai_reef_demo clean    # build/ を削除
./build_freertos.sh -l                           # 全アプリケーションをカテゴリー別に一覧表示
./build_freertos.sh build ipro7ai_reef_demo      # 名前を指定してビルド。ログは build/build.log に出力

ビルド中に行われること：

1. アプリケーションの Makefile が make -C <SDK> -f project.build PROJECT_PATH=<app dir> を実行します。プロジェクト名はアプリケーションのディレクトリ名です。
2. project.build が構成ファイルから CONFIG_CPU_ID と CONFIG_CROSS_COMPILE を読み取り、CMake を探します。まず PATH 上の cmake、次に同梱の tools/cmake/（CMake 3.15、Linux x86-64 専用）です。どちらもない場合は No cmake found で停止します。
3. CMake が Unix Makefiles ジェネレーターでビルドディレクトリを構成します。cmake/generate_autoconf.cmake が構成ファイルから include/generated/autoconf.h を書き出し、続いて bsp/、components/、アプリケーションディレクトリが追加されます。
4. make -j4 でコンパイルとリンクを行います。SDK のコンポーネントライブラリの大半は -Werror 付きでコンパイルされるため、その中で警告が 1 つでも出るとビルドが停止します。最後にリンカーが各メモリ領域の使用量を表示し、objcopy が .bin を生成します。
5. エディターのコードインデックス用に、compile_commands.json が SDK のルートにコピーされます。

CMake の開始前に [INFO] Build Path: <dir> と CPU: intelpro_ipro7 が表示されるので、どのディレクトリとツールチェーンターゲットが使われるかがわかります。

ツールチェーンのプレフィックス¶

コンパイラーのプレフィックスは、次のうち最初に設定されているものが使われます。

1. 環境変数または make のコマンドラインで指定した CROSS_COMPILE：make -C <app> CROSS_COMPILE=<dir>/bin/riscv64-unknown-elf-。
2. 構成ファイルの CONFIG_CROSS_COMPILE。出荷時の構成の多くは /opt/toolchain/riscv_ipro7/bin/riscv64-unknown-elf- を設定しています。
3. /opt/toolchain/riscv_ipro7/bin/riscv64-unknown-elf-（Windows を除く）。

cmake/toolchain.cmake はこのプレフィックスに gcc、g++、ld、objcopy を付け加えるだけで、他のパスは検索しません。次に DSP 拡張命令を試しにコンパイルし、コンパイラーが受け付ければ DSP 用のフラグを追加し、受け付けなければ標準 GCC 用のフラグを使います。

リリースパッケージがビルドホストとして記載しているのは、bash シェルを使う macOS と Linux です。project.build には Windows 用の分岐がありますが（構成ファイルを python で解析し、PATH 上の cmake を使います）、そこではデフォルトのプレフィックスを設定しないため、CROSS_COMPILE を必ず指定する必要があります。build_freertos.sh と tools/serial_monitor.py には POSIX シェルが必要です。

出力ファイル¶

build/build_out/（別構成の場合は build_<name>/build_out/）に出力されます。

<CHIP> は CONFIG_CHIP の値です。IPRO7 と IPRO7AI のすべての構成（Reef を含む）では IPRO7、ipro6_demo、ipro6_if_wifi、ipro6_fmac では IPRO6 です。build_freertos.sh のその他のアクションとオプションはツールのコマンドラインを参照してください。

.config ファイル¶

.config は Linux カーネル形式で、1 行に 1 つの設定を書きます。ビルドは次のように変換します。

各設定は -D としてコンパイラーにも渡され、同じ名前の CMake 変数にも設定されます。そのため、アプリケーションの CMakeLists.txt で if(CONFIG_SHELL) を直接判定できます。

オプションの説明はルートの Kconfig、bsp/Kconfig、components/**/Kconfig、および一部のアプリケーションの Kconfig にありますが、ビルドが読むのは構成ファイルだけで、Kconfig は評価されません。その結果：

• select は効果がありません。たとえば CONFIG_IPRO7AI_REEF と CONFIG_MM_SUPPORT は Kconfig で USE_PSRAM を select しますが、構成ファイルには CONFIG_USE_PSRAM=y を明記する必要があります。
• Kconfig のデフォルト値は適用されません。ファイルに記載のないオプションは設定されません。
• ただし、デフォルト値が 1 つだけビルドによって補われます。Reef で構成に CONFIG_IPRO7_XTAL_CAPCODE がない場合、bsp/board/ipro7/CMakeLists.txt が -DCONFIG_IPRO7_XTAL_CAPCODE=95 を追加し、[board] IPRO7AI Reef: CONFIG_IPRO7_XTAL_CAPCODE=95 (board default) と表示します。構成に明示した値が優先され、0 はチップの起動時の値をそのまま使います。これはコンパイラーの定義であり、autoconf.h の行ではありません。
• 新しい構成は、空のファイルからではなく、最も近い出荷時の構成から始めてください。

ボードキー¶

ボードキーは、board_config.h を通じて bsp/board/ipro7/ のボードヘッダーを選択します。必ず 1 つだけ設定してください。board_config.h はキーを決まった順序で判定し、CONFIG_EVB / CONFIG_DVK と CONFIG_IPRO7AI_EVK は CONFIG_IPRO7AI_REEF より先に判定されます。CONFIG_EVB=y と CONFIG_IPRO7AI_REEF=y の両方を設定した構成は、何のメッセージもなく IPRO7 EVB 向けにビルドされます。

出荷時の Reef 構成はすべて CONFIG_IPRO7AI_REEF=y と CONFIG_BOARD="IPRO7AI_REEF" を設定し、他のボードキーは設定していません。

よく使う設定¶

ビルド後、ビルドディレクトリの include/generated/autoconf.h で実際に有効になった値を確認できます。make -C apps/bluetooth/ble/ipro_ble_remote DEFCONFIG=defconfig_reef の場合：

#define CONFIG_IPRO7 1
#define CONFIG_CHIP "IPRO7"
#define CONFIG_IPRO7AI_REEF 1
#define CONFIG_BOARD "IPRO7AI_REEF"
#define CONFIG_IPRO7_FLASH_2M 1
/* CONFIG_EASYFLASH4 is not set */
#undef CONFIG_EASYFLASH4
#define CONFIG_IPRO_BLE_REMOTE_OTA 1
#define CONFIG_IPRO_BLE_CTLR_LIB "link1_periph"
#define CONFIG_EM_SIZE 16

構成ツール¶

別構成¶

複数のボードや機能に対応するアプリケーションは、複数の構成ファイルを同梱しています。.config を変更せずに 1 つを選べます。

• DEFCONFIG= はファイルを build_<name>/.config にコピーし、そこでビルドします。<name> はファイル名から defconfig_ プレフィックスと拡張子を除いたものです。defconfig_reef_ov5640 は build_reef_ov5640/ に、config_evk は build_config_evk/ にビルドされます。
• 出力ファイル名は変わりません。build_<name>/build_out/ 内の <app>_IPRO7.bin のままです。
• BOARD= を実装しているのは 2 つの Makefile だけです。ipro_agora_sentino（デフォルトは reef で .config、BOARD=evk で config_evk を選択）と ipro_pdm_mic_demo（IPRO7 EVB / IPRO7AI EVK 用アプリケーション）です。それ以外では無視されます。build_freertos.sh には BOARD オプションがないため、-d でファイルを指定してください。
• make clean の動作はアプリケーションの Makefile によって異なります。clean を project.build に渡すもの（ipro_ble_remote、ipro_throughput_test、ipro_le_audio_headset、ipro7_uvc_cam、ipro_agora_sentino）では、make clean DEFCONFIG=<file> で build_<name>/ が削除されます。ipro7ai_reef_demo、ipro_reef_teach、ipro_ai_link は build/ のみを削除し、ipro7_jpeg_decode は build/ とすべての build_*/ を削除します。それ以外のビルドディレクトリは手動で削除してください。
• コマンドラインの -j N、または build_freertos.sh -j N は外側の make にのみ適用されます。コンパイル段階は常に -j4 で実行されます。

本リリースの Reef 用構成：

ipro_ble_remote、ipro_throughput_test、ipro_le_audio_headset、ipro7_uvc_cam、ipro_ai_link、ipro7_jpeg_decode を単に make すると、別のボード向けにビルドされます。Reef では必ず Reef 用のファイルを指定してください。ipro_throughput_test/defconfig_reef を除くすべての Reef 用構成が CONFIG_USE_PSRAM=y を設定しています。パーティションテーブル、boot2、mfg ペイロードを含む各構成の書き込み方法は、サンプルと各アプリケーションの README にあります。

メモリレイアウト¶

リンカーが使える OCRAM の量は構成によって変わります。

AI と画像処理を両方有効にすると、NPU が OCRAM の上部を占有します。さらに BLE Exchange Memory が加わると OCRAM が逼迫するため、3 つすべてを必要とするアプリケーションでは構成を分ける必要がある場合があります。

• ボードに搭載されている容量を超える Flash サイズでリンクしないでください。1 MB のデフォルトは、イメージが知らないうちにパーツの容量を超えるのを防ぎます。Reef の IPRO7AI はパッケージ内に 2 MB の Flash を内蔵しています（IPRO7AI Reef EVK）。上記の Reef 用構成は、表のとおり 1 MB または 2 MB でリンクします。ipro7ai_reef_demo の .config には、その 1 MB のレイアウトはどちらのパッケージ内蔵パーツにも収まること、CONFIG_IPRO7_FLASH_2M=y を指定するとパーツ全体をリンカーに渡すことが記載されています。
• 2 MB でリンクしても、ファームウェアパーティションは大きくなりません。イメージは依然として、書き込むパーティションテーブルのファームウェアスロットに収まる必要があります（partition_cfg_2M.toml：1180 KB）。
• リンカースクリプトは bsp/board/linker/ から生成されます（テンプレートは ipro7/ipro7_common.ld.in、メモリパラメーターは configs/ipro7_flash.cmake）。アプリケーションディレクトリに <app>.ld（たとえば ipro7_uvc_cam.ld）がある場合、または構成で CONFIG_LINKER_SCRIPT="<file>" を設定している場合は、そのスクリプトが代わりに使われ、Flash サイズのキーは適用されません。
• イメージが収まるかどうかは、ビルドの最後に表示されるメモリ使用量で判断します。

アプリケーションの構造¶

apps/<category>/<app>/
├── .config            ビルド構成（必須）
├── Makefile           SDK ルートの project.build を呼び出す
├── CMakeLists.txt     ソース、インクルードパス、setup_project()
├── main.c             エントリポイント
├── Kconfig            （任意）アプリケーションのオプションの説明
├── defconfig_*        （任意）別構成
├── <app>.ld           （任意）アプリケーション独自のリンカースクリプト
├── src/  include/
└── build/             ビルド出力（自動生成）
    ├── include/generated/autoconf.h
    └── build_out/<app>_IPRO7.{elf,bin,map}

アプリケーションの CMakeLists.txt には cmake_minimum_required() や project() は不要で、SDK のビルドマクロを直接使います。

CMakeLists.txt で if(CONFIG_…) を使うと、必要な構成のときだけソースを追加できます。出荷時ファームウェアはこの方法で Wi-Fi と RTSP のソースを追加しているため、1 つのディレクトリで .config と defconfig_wifi_ipro6s の両方をビルドできます。

# Wi-Fi through the IPRO6S_FIN in CARD1 (ipronet_host over SDIO).
if(CONFIG_WIFI_USE_IPRO6S)
    target_sources(app PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src/wifi_ipro6s.c)
    ...
endif()

# RTSP MJPEG camera stream over that Wi-Fi; camera ch0 at sensor / 2.
if(CONFIG_WIFI_USE_IPRO6S AND CONFIG_RTSP_SERVER)
    target_sources(app PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src/wifi_rtsp.c)
    target_compile_definitions(app PRIVATE CAM_SCALE_DIV=2u)
endif()

すべての FreeRTOS アプリケーションは components/os/freertos/freertos_app_hooks を共有します。ヒープ、FreeRTOS のフック（idle、tick、スタックオーバーフロー、malloc 失敗）、assert にはいずれも weak のデフォルト実装があります。main() は ipro_platform_init() を呼び出し、タスクを作成してスケジューラーを開始するだけです。

• ipro_platform_init() は、プラットフォームの初期化（ボードのセットアップとコンソール UART）、ヒープ、boot2 パーティションテーブル、ログ、CONFIG_SHELL=y の場合はシェルを初期化します。アプリケーション内でシェルを再度初期化しないでください。
• ヒープ、フック、assert の定型コードを main.c に追加しないでください。vApplicationIdleHook などのフックを置き換えるには、同じ名前の weak でない関数を自分のソースで定義します。リンカーが自動的にそちらを選びます。

Reef でのハンズオン¶

出荷時ファームウェアの別構成を自分で作り、ビルドがそれをどう扱ったかを確認して実行します。この例では、ipro7ai_reef_demo の .config の記載に従い、パッケージ内蔵の 2 MB の Flash 全体でリンクします。

元に戻すには、build/ のイメージをもう一度書き込みます。次のステップ：最初の独自アプリケーションを作るで独自のアプリケーションを書き、アプリケーションのテストで確認します。

新しいアプリケーションの作成¶

最初の独自アプリケーションを作るでは、空のディレクトリから Reef 用アプリケーションを順を追って作成します。そこで従うルールは次のとおりです。

• アプリケーションは apps/<category>/<app>/ に置きます。コピーした Makefile は IPRO_SDK_BASE ?= $(abspath ../../../) で SDK のルートを見つけます。apps/bluetooth/ble/<app> のように 1 階層深い場合は ../../../../ にする必要があります。Makefile は貼り付けずにコピーしてください。レシピ行はタブで始まる必要があります。
• .config は apps/platform/ipro7ai_reef_demo/.config から始め、不要なものを削除します。1 行目のコメントが、./build_freertos.sh -l で表示される説明になります。
• CMakeLists.txt はアプリケーションの構造のマクロを使って書きます。setup_project() に渡す名前はディレクトリ名と一致させる必要があります。

• main.c は最小限にします。

  main.c

  #include <FreeRTOS.h>
  #include <task.h>
  
  #include "freertos_app_hooks.h"
  
  static void app_task(void *arg)
  {
      (void)arg;
      for (;;) {
          vTaskDelay(pdMS_TO_TICKS(1000));
      }
  }
  
  int main(void)
  {
      ipro_platform_init();   /* platform, heap, boot2, log, shell */
      xTaskCreate(app_task, "app", 1024, NULL, 5, NULL);
      vTaskStartScheduler();
      for (;;) {
      }
  }
  

本リリースの制限事項¶

• 対話的な構成ツールはありません。リリースパッケージでは make menuconfig と make defconfig は動作しません（構成ツールを参照）。
• Kconfig は評価されないため、依存するオプションは構成ファイルに書き込む必要があります。ビルドが補うデフォルト値は Reef の水晶発振子トリムだけです。
• BOARD= が動作するのは ipro_agora_sentino と ipro_pdm_mic_demo だけです。
• リリースパッケージに記載されているビルドホストは macOS と Linux だけです。

関連ドキュメント¶

• 最初の独自アプリケーションを作る：空のディレクトリから作る Reef 用アプリケーション。
• アプリケーションのテスト：コンソールでの確認、セルフテスト、build_freertos.sh test。
• システムアーキテクチャ：レイヤー、コンポーネント、ディレクトリ。
• BLE 開発：.config の BLE 設定。
• ツールのコマンドライン：build_freertos.sh のすべてのアクションとオプション。
• サンプル：各アプリケーションが同梱する構成。