rust-embedded

Rust 組み込みファームウェアの開発

まずハードウェアの事実を確認してから、抽象化とフレームワークを選択してください。特定の開発ボード向けのサンプルコードを移植可能なものとして扱わないでください。また、ハードウェア上の根拠がないまま、ファームウェアが使用可能だと主張しないでください。

タスクの種類を判断する

次の成果物を区別してください。

1. 移植可能な no_std ライブラリまたはドライバー：中核ロジックはモック HAL を使ってホスト上でテストする必要があります。
2. 特定の MCU／開発ボード向けファームウェア：ターゲット、ランタイム、HAL／PAC、メモリ配置、書き込みツール、ハードウェア受け入れテストが必要です。
3. ボードサポートまたはブートコード：リンク、起動、クロック、ピン、安全性の不変条件に重点を置きます。
4. 組み込み Linux アプリケーション：通常は std を使用します。デバイスインターフェースやクロスコンパイルが関係しない限り、CLI、Web、または並行処理アプリケーションとして扱います。

必須のハードウェア要件

変更を加える前に、以下を確認して記録してください。

• 正確な MCU モデル、アーキテクチャ、開発ボードのリビジョン、周辺機器の接続状況；
• Rust ターゲットトリプル、ツールチェーン／MSRV、ビルドプロファイル；
• ランタイム、HAL、PAC、BSP、embedded-hal、実行フレームワークの実際のバージョン；
• フラッシュ／RAM の開始アドレスと容量、ブートローダーのソース、リンカースクリプトの由来；
• デバッグプローブ、通信プロトコル、書き込みツール、アクセス許可；
• クロック、ピンの多重化、電圧、バスのアドレス／モード／周波数；
• 並行処理モデル：ベアメタル割り込み、クリティカルセクション、RTIC、Embassy など；
• 可観測性の手段：defmt、UART、RTT、LED、ロジックアナライザーなど；
• 実機での受け入れ手順とセキュリティ上の制約。

チップのメモリ配置やピン設定が不確かな場合、値を捏造しないでください。既存の BSP、データシート、リファレンスマニュアル、プロジェクトリポジトリ内のロックされたドキュメントを優先して確認してください。

ワークフロー

1. ビルドのベースラインとハードウェアの基盤を確立する

リポジトリの設定、ターゲットの選択、依存関係の取得元を確認します。

rustc --version --verbose
rustup target list --installed
cargo metadata --format-version 1
cargo tree -e features

.cargo/config.toml、リンカーパラメーター、memory.x／リンカースクリプト、build.rs、ランナー、チップの機能フラグ、既存の書き込みコマンドを確認します。まず現在のビルドを再現するか、失敗ログを保存してください。

ターゲット、ランタイム、またはメモリ配置を選択するときは、ターゲットとランタイムをお読みください。

2. 最小限の起動経路を確立する

複雑な周辺機器を統合する前に、特定のターゲット上で最小限のファームウェアが正しくビルドされ、確認可能なイメージが生成されることを確認してください。

Reset/Startup Code
    -> Initialize Memory and Runtime
    -> Initialize Clocks and Required Peripherals
    -> Enter Unique Application Entry Point
    -> Produce Observable Heartbeat or Diagnostics

• ベアメタルのバイナリでは通常 #![no_std] を使用します。#![no_main] を使用するかどうかはランタイムによって異なります。
• グローバルアロケーター、メモリ領域、障害発生時の戦略を用意した後にのみ alloc を使用してください。
• パニック時のポリシーは、デバイスの制約とデバッグ環境の両方に適したものにする必要があります。
• メモリ配置は、他の開発ボードのサンプルコードをコピーするのではなく、チップ／BSP／ブートローダーの情報に基づいて決定してください。Cortex-M、RISC-V など、単一のアーキテクチャを前提とする設定をハードコードしないでください。

3. 移植可能なロジックとボード固有の配線を分離する

推奨する境界は次のとおりです。

Pure Domain Logic (No Hardware Dependencies)
    -> portable driver (core + embedded-hal traits)
    -> board adapter (specific HAL/PAC, pins, clocks)
    -> firmware binary (startup, tasks, failure strategies)

• 移植可能なドライバーは embedded-hal のトレイトに依存し、特定の PAC シングルトンには依存しません。
• ボード層では実際の周辺機器を扱い、ピン、クロック、DMA を設定します。
• PAC に直接アクセスするのは、HAL では起動処理やパフォーマンス上の要件を表現できない場合に限ります。GPIO、バス、プロトコルのエラーを .ok() で暗黙に破棄しないでください。
• レジスター、DMA、ベアメタルポインター、FFI に関する安全性の前提を SAFETY コメントに記述し、rust-unsafe-ffi を使って詳細にレビューしてください。

4. 並行処理モデルを選択する

同じファームウェア内で、ベアメタル割り込み、複数のエグゼキューター、異なるリソースロックモデルをむやみに混在させないでください。

• ベアメタル割り込み：ISR が実行時間の上限を守り、ブロックせず、メモリ割り当てを最小限に抑えていることを確認してください。処理はメインループまたはタスクに委譲してください。
• クリティカルセクション：割り込みマスク時間を最小限に抑え、優先度逆転とネストのセマンティクスを明示的に定義してください。
• RTIC：リソースロックのバージョン、優先度、タスク API がロックのバージョンに対応していることを確認してください。
• Embassy：エグゼキューターの構成、タイムドライバー、チップとの統合、キャンセル時の動作を確認してください。
• DMA：バッファーの所有権と送信のライフサイクルは、型または明確な不変条件によって制約する必要があります。

HAL、共有状態、またはフレームワークの選択が必要な場合は、HAL and Concurrencyをお読みください。複雑な言語レベルの並行処理セマンティクスには、rust-concurrencyを使用してください。

5. 可観測性と障害対応戦略を強化する

• 開発ビルドでは、復旧可能なログ／プローブの経路を用意してください。
• ログ出力のタイミングによって、割り込みやリアルタイムの問題が見えにくくならないようにしてください。
• 開発者によるパニック、ハードウェアウォッチドッグによるリセット、本番環境でのグレースフルな縮退戦略を区別してください。
• センサーのタイムアウト、バスエラー、チェックサムの失敗、周辺機器の利用不可について、原因を把握できる情報を保持してください。

デバイスキー、ペアリング認証情報、または機密性の高い識別子をログに漏らさないでください。

6. 段階的な検証

高速なものから順に検証してください。

1. 純粋なロジックに対するホストユニットテスト。
2. ドライバープロトコルとエラーパスのテストに、モックのembedded-halを使用する。
3. 実際のターゲットに対して、関連するすべての機能／プロファイルをクロスコンパイルする。
4. ELF、セクション、シンボル、イメージサイズ、スタック／ヒープの予算を確認する。
5. 書き込みを実行し、プローブ／UARTログを保存する。
6. 実際のハードウェアで、ピン、バス、タイミング、割り込み、リセット経路を検証する。
7. 必要に応じて、オシロスコープまたはロジックアナライザーで電気的特性とタイミングの事実を確認する。

証拠の完全な一覧は、Hardware Validationを参照してください。

よく使うコマンド

リポジトリの構成に応じて、<target>と<package>を置き換えてください。

cargo fmt --all -- --check
cargo test -p <portable-package> --all-targets
cargo clippy -p <portable-package> --all-targets -- -D warnings
cargo build -p <firmware-package> --target <target> --release
cargo size -p <firmware-package> --target <target> --release

cargo sizeには、プロジェクトのインストールとcargo-binutilsが必要です。そうでない場合は、リポジトリにある既存のELF／セクション確認ツールを使用してください。書き込みまたは実行コマンドは、ランナーがそのターゲット向けに構成され、ハードウェアの目的が確認されている場合にのみ実行してください。書き込みはデバイスの状態を変更します。対象を正確に特定してから、ユーザーの許可範囲を厳守してください。

完了条件

• ハードウェアの契約、依存関係のバージョン、メモリレイアウトの情報源が明確に定義されている。
• 移植可能なロジックがボード固有のコードから分離され、エラーが黙って無視されない。
• ホストテストとターゲット向けクロスコンパイルが成功している。
• 並行処理、DMA、レジスター、またはunsafeに関する不変条件が文書化されている。
• イメージサイズとリソースの予算が確認されている。
• 実際のハードウェアでの受け入れに、ログまたは測定の証拠がある。

検証中に実際のハードウェアを利用できない場合は、「Build Verification Only」と記載してください。

引き継ぎの境界

主な問題	担当先
ベアポインター、MMIO、FFI、安全性をカプセル化する不変条件	rust-unsafe-ffi
非同期処理、キャンセル、Send/Syncおよび一般的な並行処理のセマンティクス	rust-concurrency
ホストテスト、属性テスト、カバレッジまたはベンチマーク	rust-testing
ターゲット構成、機能フラグ、ビルドスクリプト	rust-cargo-build
言語の所有権、トレイト、エラー、core API	rust-stable

オンデマンドリソース

• ターゲットとランタイム：ターゲット、起動、またはメモリレイアウトを確認する際に読みます。
• HAL と並行処理：割り込み、RTIC、Embassy タスクのドライバーコードを作成する際に読みます。
• ハードウェアの検証：ビルド、書き込み、測定、結果の報告を行う際に読みます。
• シナリオの例：タスク分割のテンプレートが必要な際に読みます。
• examples/golden-no-std/：ホストでコンパイル可能で、モックテストに対応した no_std ドライバー境界の例です。

基礎資料

• The Embedded Rust Book
• Rust Embedded Working Group
• embedded-hal
• The Rust Reference: no_std