パーティションテーブル¶
SiFli-SDKのpartition_tableビルドツールは、ボードのパーティション定義を読み込み、アプリケーションで使用するパーティションマクロを含むptab.hを生成します。パーティションテーブルでは、NOR Flash、NAND Flash、eMMC、SDカード、PSRAM、オンチップSRAMなど、対象メモリーのアドレス配置を定義します。
各ボードには既定の配置があり、そのボード向けにビルドされるアプリケーションはすべてその配置に従います。プロジェクト側で独自のパーティションテーブルを指定し、ボードの既定値を置き換えることもできます。
パーティションテーブルを有効にする¶
ミドルウェア設定で「すべてのメモリーレイアウトの管理にパーティションテーブルを使用（Use partition table to manage all memory layout）」を有効にします。また、プロジェクトのKconfig.projに次の設定が必要です。SiFli-SDKのサンプルには、この設定がすでに含まれています。
# APP-specific configuration.
config CUSTOM_MEM_MAP
bool
select custom_mem_map
default y if !SOC_SIMULATOR
形式を選ぶ¶
SiFli-SDKは、3種類のパーティションテーブル形式に対応しています。既存のボードや製品でv1/v2を維持する必要がない限り、新規開発ではv3を使用してください。
| 形式 | 定義ファイル | 主なモデル | 新規プロジェクトでの使用 |
|---|---|---|---|
| v1 | ptab.json |
JSONのメモリー一覧、タグ、任意のftab、img、execメタデータ |
いいえ。既存プロジェクトの保守に限ります。 |
| v2 | ptab.json |
名前付き・型付きのイメージ／実行パーティションを持つJSONのメモリー一覧 | いいえ。既存ボードが依存している場合に維持します。 |
| v3 | ptab.yaml |
type、subtype、region、exec、生成マクロ、プロジェクトオーバーレイを使うYAMLパーティション |
はい。 |
ビルドシステムは最初にptab.yaml（v3）を検索し、見つからない場合はptab.json（v1/v2）を検索します。検索順は、ボードディレクトリ、チップディレクトリ、BSPルート、customer/boards/<board>/です。
v1：JSONタグとイメージメタデータ¶
v1はptab.json内のJSON配列で定義します。専用のバージョンフィールドはありませんが、先頭要素に任意で"version": "1"を含めることができます。
各メモリー項目では、次の情報を定義します。
mem：flash2やpsram1などのメモリー名。base：メモリーの16進数ベースアドレスです。対象メモリーのマップに照らして値を確認してください。regions：そのメモリー内のパーティション一覧。
各regionでは、オフセットと最大サイズをバイト単位でoffsetとmax_sizeに指定します。tagsの値からパーティションマクロが生成されます。たとえばFLASH_BOOT_LOADERを指定すると、FLASH_BOOT_LOADER_START_ADDR、FLASH_BOOT_LOADER_OFFSET、FLASH_BOOT_LOADER_SIZEが生成されます。開始アドレスは、メモリーのbaseにregionのoffsetを加えた値です。
| フィールド | 用途 |
|---|---|
ftab |
Flash Tableのエントリーを記述します。 |
img |
生成される書き込みスクリプトで使う、パーティション内イメージの名前です。複数のバイナリを出力するプロジェクトではproj_name:binary_nameを指定します。 |
exec |
共有リンカースクリプトがコードアドレスを選択するための実行プログラム名です。 |
custom |
生成されるptab.hに整数値のカスタムマクロを追加します。 |
PSRAMにはCBUSとSBUSの別々のアドレス空間があります。コードの実行アドレスにはCBUSパーティションにexecを指定します。コードのコピー元としてSBUSアドレスを使う場合は、SBUSパーティションのftabにxipアドレスを設定します。
v2：名前付き・型付きJSONパーティション¶
v2もptab.jsonを使いますが、ヘッダーで"version": "2"を宣言する必要があります。メモリーのフィールドはmem、base、regionsのままです。各regionではoffsetとmax_sizeを指定し、tagsとcustomも使用できます。さらに、regionのname、type、実行用パーティションの場合は任意のcoreを指定します。
| フィールドまたは型 | 意味 |
|---|---|
name |
パーティション名です。プログラムイメージ名は、対応するプログラム名またはAddCustomImg名と一致させる必要があります。複数ファイルのプログラムではproj_name:1、proj_name:2のように指定できます。 |
core |
app_execパーティションを実行するコアです。hcpu、lcpu、acpuを指定します。 |
app_img |
プログラムイメージを格納するプライマリパーティションで、Flashツールによる書き込み対象です。 |
app_img2 |
更新用に通常はプライマリパーティションと組み合わせる、バックアップ用プログラムイメージパーティションです。 |
app_exec |
プログラムを実行するアドレス空間です。 |
bootloader、main、dfu、ftabは予約済みの名前です。acpuなど、その他のプログラム名はユーザー定義イメージに使用できます。テーブルにftabパーティションとbootloaderパーティションの両方が定義されていない場合、ツールは既定の構成を生成します。利用する前に、生成されたptab.hを確認してください。
v3：YAMLパーティションとオーバーレイ¶
v3はptab.yamlを使う推奨形式です。従来のtagsモデルを明示的なtypeとsubtypeに置き換え、論理region名によってパーティションと物理メモリー構成を分離します。また、ビルド時にptab.h、ftab.bin、リンカースクリプト用断片を生成します。
| スコープ | フィールド | 必須 | 意味 |
|---|---|---|---|
| トップレベル | version |
はい | 3である必要があります。 |
| トップレベル | chip |
はい | SF32LB525UC6などのチップ品番です。 |
| トップレベル | memory |
いいえ | 外部ストレージの定義です。 |
| トップレベル | partitions |
はい | パーティション一覧です。 |
| パーティション | name、type、region、offset、size |
はい | 名前、種別、論理ストレージ領域、配置を指定します。offsetとsizeには0x形式の値、またはKB／MBサフィックス付きの値を指定できます。 |
| パーティション | subtype、exec、core、attrs |
いいえ | 詳細種別、XiPを使わないコードの実行先、対象コア、カスタム属性を指定します。 |
外部memoryの各定義では、mpiまたはsdmmcインターフェース、nand、nor、sdのいずれかのtype、およびサイズを指定します。regionはこれらの外部メモリーに加え、hpsys_ramまたはlpsys_ramを参照できます。
各regionは、SBUSのストレージアドレスと、CPU実行またはXiPに使うCBUSアドレスに対応します。SDKはチップのSiliconSchemaデータからこのマッピングを読み込みます。FAL_PART_TABLEのデバイス名はexecではなく、パーティションのストレージregionに基づきます。mpi1～mpi5はNOR_FLASH1_DEV_NAME～NOR_FLASH5_DEV_NAMEに、sdmmc1とsdmmc2はそれぞれSDMMC1_DEV_NAMEとSDMMC2_DEV_NAMEに対応します。
| 型 | サブタイプまたは用途 | 意味 |
|---|---|---|
ftab |
— | Flash Tableパーティションです。 |
bootloader |
— | ブートローダーパーティションです。 |
app |
factory |
工場出荷用のメインアプリケーションです。CODE_START_ADDRとCODE_SIZEを生成します。 |
app |
dfu |
独立したDFUアプリケーションです。 |
app |
ex |
リソースパーティションです。ビルドにより、ツールチェーン固有のリソースイメージ出力が生成されます。 |
data |
flashdb_kv |
FlashDB KVデータベースです。KVDB_*マクロを生成し、FAL_PART_TABLEに登録されます。 |
data |
filesystem、littlefs、fat、fatfs |
filesystemはFS_REGION_*マクロを生成し、FAL_PART_TABLEに登録されると説明されています。一方、同じドキュメントの別の箇所ではlittlefs、fat、fatfsもマクロを生成するサブタイプとして列挙され、現在は効果がないとも記載されています。これら3つの動作は対象SDKリリースで確認してください。また、同じマクロ説明ではサブタイプ名にflashdbを使っていますが、サブタイプ表とFALの規則ではflashdb_kvを使っています。対象SDKで確認せず、両者を別名として扱わないでください。 |
data |
ram、calibration、raw、int_res |
RAM、キャリブレーションデータ、アプリケーション管理のrawデータ、またはELFにリンクされセクション名で分割される内部リソースデータです。 |
v3が自動生成するFAL_PART_TABLEに含まれるのはdata/flashdb_kv、data/filesystem、およびサブタイプがexではないappパーティションのみです。ftab、bootloader、app/exと、littlefs、fat、fatfs、raw、ram、calibration、int_resなどその他のdataサブタイプは含まれません。生成エントリーでは各パーティションのnameが使われ、旧レイアウトの別名main、dfu_code、fs_rootは実際のパーティション名に変換されません。v3への移行時にFAL_PART_TABLEを手動定義しないでください。ボード側にcustom_mem_map.hがある場合は、再定義警告を避けるため削除してください。
ptab.hは各パーティションに<NAME>_START_ADDR、<NAME>_SIZE、<NAME>_OFFSETマクロを生成します。<NAME>はパーティション名を大文字にしたものです。regionのメモリー種別をSDKが認識できる場合は、<NAME>_MEM_TYPEも生成されます。app/factoryパーティションでは、execが指定されていればCODE_START_ADDRにそのアドレスを使い、指定がなければパーティションのCBUSアドレスを使います。
NAND Flashに格納したアプリケーションをPSRAMにコピーする場合のように、その場でコードを実行できないときはexec: {region, offset}を使います。execを指定しない場合、生成されるコード開始アドレスにはパーティションのCBUSストレージアドレスが使われます。attrsを指定すると、ptab.hにカスタムマクロが追加されます。
既定値とプロジェクトオーバーレイ¶
該当するパーティションがない場合、v3はシステム既定値を導出します。SF32LB52では、HCPUの工場出荷用アプリケーションのストレージ領域からflash_tableとbootloaderを推定できます。また、NANDまたはSDMMCをブート用ストレージとして使う場合も、ドキュメントに記載された既定のデータパーティションが追加されます。SF32LB56とSF32LB58では、内部mpi5上のflash_tableとbootloaderを省略できます。既定のSiP PSRAMウィンドウと標準RAMパーティションも、プロジェクトでRAM配置を変更しない限り省略できます。
小規模なプロジェクト固有の変更には、ボードのptab.yaml全体をコピーするのではなく、ptab.overlay.yamlを使用します。パーティションの追加や既存パーティションの上書きができます。
partitions:
- op: override
name: fs_region
size: 5MB
- op: add
name: log_region
type: data
subtype: raw
region: mpi2
offset: 0x00F00000
size: 64KB
ボード固有のオーバーレイはチップ固有のオーバーレイより優先されます。変更できるのはパーティションだけで、memory、chip、versionの変更やパーティションの削除はできません。オーバーレイはボードレベルのv3 ptab.yamlにのみ適用でき、プロジェクトレベルの完全なptab.yamlまたはptab.jsonとは併用できません。ボードがv1/v2のptab.jsonを使い、完全なptab.yamlも選択されていない場合、ビルドは警告を出してオーバーレイを無視し、従来の非オーバーレイ経路で処理を続けます。この場合、ptab.effective.yamlは生成されません。オーバーレイが適用された場合は、確認用に最終結果がptab.effective.yamlに出力されます。
生成ファイルと検証¶
| 出力 | 用途 |
|---|---|
ptab.h |
パーティションマクロを含む生成済みCヘッダーです。 |
ftab.bin |
ブートローダーが使用するFlash Tableのバイナリです。v3ではftabサブプロジェクトを使わず、Pythonから直接生成されます。 |
link_copy.lds／link_copy.sct |
GCCまたはKeil用に生成されるリンカースクリプトのコピーです。v3ではJinja2テンプレートを使います。 |
ptab.effective.yaml |
オーバーレイが有効な場合に生成される、適用後のv3テーブルです。 |
統合前に、v3のボードテーブルを検証します。
バリデーターは、パーティション名の構文、型とサブタイプ、regionの有効性、パーティション領域の重なり、ブートローダーの一意性を確認します。ビルドで使用されたv3の有効な構成を確認するには、次を実行します。
sdk.py ptab-export --board=<board-name>
sdk.py ptab-export --board=<board-name> --output /tmp/ptab.effective.yaml
sdk.py ptab-export --strict
生成されたFlash Tableを確認する¶
ビルド後、ftab.binはビルドディレクトリに出力されます。SDK環境を初期化してから、現在のプロジェクト配下で最初に見つかったbuild_*/ftab.binを確認します。
Windows PowerShellでは./export.ps1で初期化します。ボードごとのビルドディレクトリが複数ある場合はパスを指定し、スクリプトから結果を利用するときはJSON出力を使います。
sdk.py ftab-dump --path build_<board_name>/ftab.bin
sdk.py ftab-dump --path build_<board_name>/ftab.bin --format json
テーブル表示には、パーティションエントリー、DFUと起動フローで使うイメージの説明、HCPU、LCPU、ブートローダー、ブートイメージそれぞれの実行中イメージを指すポインターが表示されます。
製品レビュー¶
- ボードのテーブルを使うのか、プロジェクト固有の構成を使うのかを意図的に選択している。
- 選択したv1、v2、v3の構文が、ビルドシステムが実際に検出するファイルと一致している。
- 特にXiP以外のストレージやPSRAMについて、イメージの格納先と実行位置が正しい。
- アプリケーション、バックアップ、DFU、ファイルシステム、キャリブレーション、アプリケーション管理データに十分な容量があり、領域が重複していない。
- 生成された
ptab.h、ftab.bin、およびv3オーバーレイを使う場合はptab.effective.yamlを確認している。 - 通常の更新経路とは別に、復旧用の書き込み手順を記録している。
詳細は、SiFli-SDKの公式ドキュメント パーティションテーブル、v1、v2、v3 を参照してください。
最終更新: