既存の組込みコードベースを引き継ぐ

要点: 既存ファームウェアの引き継ぎは、今あるものを確保してビルドを再現可能にすることから始め、次に報告された市場不具合を作業台の機器で再現します。そこまで済んでから初めてコードの全体像を把握し、リスクを書き出し、安全で効果の大きい問題から修正します。作り直しを検討するのは、古い構造が新しい不具合を生み続けていることが根拠で示された場合だけです。

既存ファームウェアの引き継ぎを5つのフェーズで示すフローチャート:資産の確保、再現可能なビルド、不具合の再現、把握と評価、修正とリリース。評価の後の分岐点で的を絞った修正か部分的な作り直しかを選び、各フェーズは文書の成果物を出す。
図1. 引き継ぎのフェーズと成果物。修正か作り直しかの判断は評価の後で行い、前には行わない。

1.0 よくある出発点

典型的な引き継ぎはこうです。元の開発者や委託先はもういません。ソースコードはアーカイブの中か、一部が誰かのノートPCにあります。ビルドは1台のマシンでしか通らず、そのツールチェーンを誰がインストールしたのか誰も覚えていません。機器は市場に出ていて、リセット、フリーズ、特定のスマートフォン機種でだけ動かない機能といった報告が届いています。早く直せという圧力がかかっています。

すぐにコードを読んでパッチを当てたくなります。しかし再現可能なビルドと再現できた不具合がないまま、見当違いの原因を狙ったパッチを出すと、最初の不具合の隣に2つ目の不具合を出荷することになります。

2.0 フェーズ1:資産を確保する

なくなる前にすべて集めます。

資産重要な理由
ソースコード、全ブランチとアーカイブ言うまでもない。複数のコピーを探して比較する
ツールチェーンのインストーラと正確なバージョンコンパイラのバージョンでコード生成とタイミングが変わる
ビルドスクリプト、IDEのプロジェクトファイル、リンカスクリプトソースにない最適化フラグ、メモリ配置、defineを含む
現在市場にあるバイナリとそのバージョンどのソースがどの機器に対応するかの証拠になる
ブートローダのソースと鍵(あれば)これがないと機器を更新できない可能性がある
書き込みツールと生産ラインの手順新しい機器を作るのに必要
各基板版のハードウェア設計データファームウェアは基板版で分岐している
不具合報告、現地のログ、顧客のメール不具合の証拠

ソースがまだバージョン管理されていなければ、すぐに管理下に置き、アーカイブを無加工のまま最初のコミットにします。署名鍵や認証情報はリポジトリではなく、適切な鍵の保管場所に入れます。

製品に関わった人には、連絡がつくうちに話を聞いてください。前の開発者、生産ライン、サポートチームです。前の開発者と1時間話すだけで、コードから掘り起こすと何日もかかるビルドの癖や現地での回避策が分かることがあります。聞いた内容は書き残し、リポジトリと一緒に保管します。

3.0 フェーズ2:ビルドを再現可能にする

目標は、ソースから市場のものと同一のバイナリを作るか、違いを1つずつ説明できるようにすることです。

  1. コンテナか文書化した仮想マシンにツールチェーンを再構築し、バージョンを固定する。
  2. ビルドして、出力を市場のバイナリと比較する。埋め込まれたビルド日時やパスの違いは想定内だが、コードの違いは想定外である。
  3. 一致しなければ、一致するソースのリビジョンを探す。どのリビジョンも一致しなければ、それを所見として記録する。市場のファームウェアには、コミットされなかった変更が含まれている可能性がある。
  4. ビルドスクリプトとCIを整え、誰でもコマンド1つでビルドできるようにする。

Reproducible Buildsプロジェクトの定義は、目標とする基準として役立ちます。部分的な再現性でも、市場で実際に動いているコードを扱っているかどうかは分かります。

4.0 フェーズ3:不具合を再現する

市場にあるハードウェア版に合わせた評価用機器を1台以上用意します。報告された不具合ごとに次を行います。

  • 報告された症状と条件を書き出す:ファームウェアのバージョン、ハードウェア版、環境、操作の順序。
  • ファームウェアにログやトレースがなければ追加する。それ以外は市場版と同じ、別のビルドで行う。
  • 疑わしい条件を変えながら再現を試みる:電源品質、温度、電波環境、長時間動作、特定のホスト機器。
  • 何が再現し、何が再現しなかったか、どの程度確かかを記録する。

作業台では再現しない不具合もあります。その場合はそう明記し、仮説と、役に立つ現地データ(たとえば貴社が選んだ現地の機器でのログ出力用ビルド)を併記します。

5.0 フェーズ4:把握と評価

ここで初めて、目的をもってコードを読みます。次の項目を扱う短い評価書を書きます。

領域確認する点
構造モジュール、階層、ハードウェアアクセスの整理のしかた
並行性割り込みハンドラ、RTOSタスク、共有データ、優先度
メモリスタックサイズ、ヒープの使い方、バッファの扱い、静的解析の指摘
エラー処理周辺回路の故障やタイムアウト時の挙動、ウォッチドッグの使い方
更新経路機器を更新できるか、どの程度安全か
テスト既存のもの、安く追加できるもの
ハードウェアとの結合基板版への依存、部品に結び付いたマジックナンバー

古いコードに静的解析ツールや高いレベルのコンパイラ警告をかけると、長いリストが出てきます。すべてを消そうとはせず、報告された不具合の原因になっている可能性の高い順に仕分けます。

6.0 フェーズ5:修正、検証、リリース

効果とリスクの比が最も良い問題から修正します。それぞれ小さなレビュー済みの変更とし、修正前は不具合を再現し修正後は合格するテストを付けます。修正は、変更をできるだけ少なくしたバージョンで出荷します。リリースをいつ出し、いつ全機器に展開するかは、DevSolderが提供するテスト結果をもとに貴社のチームが判断します。

6.1 修正か、作り直しか

兆候向かう方向
不具合が少数の具体的な欠陥に行き着く的を絞った修正
市場に製品があり、更新経路が機能している的を絞った修正、その後に段階的なリファクタリング
タスク間の保護されていない共有状態など、同じ構造上の原因から新しい不具合が出続けるそのサブシステムの部分的な作り直し
いずれにせよハードウェアプラットフォームが変わる新プラットフォームと合わせて作り直しを検討できる
再現可能なビルドがなく、主要部分のソースが欠けている欠けた部分の作り直しは避けられない

市場にあるファームウェアの全面的な作り直しには、それ自体のリスクがあります。古いコードには、誰も書き残さなかった問題への対処が埋め込まれているからです。システムの一部の作り直しを勧める場合は理由を示し、古い挙動をテストの基準として残します。

7.0 各フェーズで得られるもの

  • 資産の一覧と、元のアーカイブを起点にしたリポジトリ。
  • ツールチェーンを文書化し、CIを備えた再現可能なビルド。
  • 不具合の再現報告書。
  • リスクに順位を付けたコード評価書。
  • テストとリリースノートを伴う修正。

これらの成果物は、作業をDevSolderで続けるかどうかにかかわらず役に立ちます。依頼の始まり方は既存ファームウェアの引き継ぎ・市場不具合対応のページで、新規のファームウェア開発は組込みファームウェアで説明しています。状況をお伝えいただくには、プロジェクトのご相談をご利用ください。

参考資料

よくあるご質問

前の委託先がソースコードを渡してくれません。どうすればよいですか?

手元にあるもの、つまりバイナリ、実機、残っている資料から始めます。そこから理解できる動作もあり、評価によってどの部分を書き直す必要があるかが分かります。前の委託先との契約も確認してください。ソースコードの納品条件がすでに含まれていることがあります。

最初の不具合を直せるまでにどれくらいかかりますか?

ビルドの再現と不具合の再現にどれだけ時間がかかるか次第です。この2つは修正そのものより所要時間のばらつきが大きいため、それぞれの進捗を報告し、両方が済んだ時点で修正の見積もりを出します。

市場にある機器にアクセスできなくても作業できますか?

まず同じハードウェア版の評価用機器で作業を始めます。現地の機器へのアクセスが必要になるのは、不具合が設置状態、配線、電波環境に依存する場合だけです。その場合は、貴社が選んだ現地の機器にログ出力用のビルドを入れるのが、データを得る現実的な方法です。

コードのスタイルや構造を変えますか?

変えるのはリスクが下がる箇所だけです。初期の修正は小さく保ち、レビューしやすいよう既存のスタイルに合わせます。大きなリファクタリングは、テストが整ってから理由を添えて別途提案します。