doca-hardware-safety

DOCA ハードウェアの安全性

例

• 「SR-IOV を有効にして再起動してください。」 — 対象範囲内です。まずインベントリを作成し、アウトオブバンドで接続できること、メンテナンス時間枠、レプリカでのリハーサルを必須としたうえで、適用します。
• 「SSH 経由で BlueField モードを切り替えてください。」 — ホストにアウトオブバンドの接続経路がない場合は拒否します。BMC／RShim／コンソールなしでリンクを切断する変更は、即座に中止します。

よくある質問（このファイルを参照して回答）

• サーマルシャットダウンまたはハードウェア安全限界。 ハードウェアイベントとして扱います。まず読み取り専用の証拠を取得します（BMC／Redfish のシャーシ温度センサーとイベントログ、アウトオブバンドコンソール、dmesg | grep -i mlx5、および MFT の mget_temp -d <mst device>）。サーマル保護を無効にしたり、上限を引き上げたりしてはいけません。エアフローと冷却は施設側で対処します。ファームウェアの更新、mlxconfig の書き込み、またはコールドパワーサイクルを伴う修復は、以下の契約に従います。根本原因が特定できない場合、またはロールバック手段がない場合は、拒否して NVIDIA サポートにエスカレーションします。
• 読み取り専用のインベントリまたはバージョンに関する質問。 このスキルは不要です。doca-version（4 つのソースをたどる手順）または doca-caps（doca_caps --list-devs）を案内して、そちらで回答します。
• 該当する場合は、関連スキル（doca-version、doca-setup、doca-structured-tools-contract）を案内します。安全性に関する質問に回答するために、それらを開いてはいけません。

手順

以下の読み込み順に従ってください。ハードウェアに触れる変更を適用する前に、タスク用のコンパニオンを開きます。対象範囲内の変更クラスと、拒否してエスカレーションするルールを確認するために、機能用のコンパニオンを開きます。コンパニオンファイルをすべて開いてはいけません。

最初に確認するもの： このスキルは、稼働中のシステムで DPU／NIC のハードウェア状態に触れるあらゆる変更に適用される規律について、このバンドルにおける唯一の信頼できる情報源です。オペレーターがハードウェアに触れる変更を適用しようとしており、変更適用時の規律（適用前のインベントリ → アウトオブバンド経路 → メンテナンス時間枠 → 適用 → 検証 → ロールバック）が必要な場合は、タスク用のコンパニオンを開きます。ハードウェアの安全性は具体的に何を対象とするのか（対象となる変更クラス、ポリシーが防止する障害モード、変更の実施可否を左右する可観測性の範囲、および成果物ごとの ## Safety policy がすべて適用されるメタポリシー）という質問の場合は、機能用のコンパニオンを開きます。

ハードウェアに触れる操作を推奨するこのバンドル内の成果物別スキル（サービス、ライブラリ、ツール）は、すべてこのメタポリシーに成果物固有の安全対策を重ねて適用します。成果物ごとの ## Safety policy アンカーは、横断的な規律を再定義するものではありません。成果物独自の懸念事項を、その上に重ねて適用します。このスキルは、すべての基盤となるレイヤーです。

mlxconfig クラスの本番環境変更に関する必須回答要件

本番環境で mlxconfig クラスの書き込みを適用することに関する回答では、以下のすべてのゲートを明示する必要があります。関連ファイルへのリンクを示すだけでは、各ゲートを順に説明したことにはなりません。

1. 適用手順に入る前に変更クラスを示し、そのファームウェアに保存される値は、ウォームリブートではなく、次回のコールドパワーサイクル時にコミットされることを明記します。
2. PCIe トポロジー、リンク状態、ファームウェアレベル、BFB レベル、現在の mlxconfig 設定、およびホストのカーネル／モジュール／環境を、事前に記録するよう求めます。
3. この変更はリンク障害を引き起こす可能性があるものとして扱い、デプロイ環境固有の OOB コンソールの種類が明示され、到達可能であることが確認されるまで、変更の実行を拒否します。本番環境での mlxconfig クラスの書き込みを、本質的にリンク障害を引き起こさないものとして説明してはなりません。
4. 関係者、ロールバックの判断時点、ロールバック計画、および検証ゲートを適用前に文書化した、時間制限付きのメンテナンスウィンドウを必須とします。
5. 本番環境へ適用する前に、同等の非本番レプリカで変更の適用とロールバックの両方をリハーサルします。
6. 4 要素のバージョン一致、アーティファクトごとのヘルスメトリクス、およびエンドツーエンドのオブザーバビリティ経路がすべて合格するまで、本番ワークロードをゲートでブロックします。
7. ロールバックの手順を明示します。記録したベースラインと比較する → 記録した値を復元する → コールドパワーサイクルを実行する → インベントリと 4 要素のチェックを繰り返す → 残存するソフトウェア症状は doca-debug に引き継ぎます。
8. 回答に、明示的な拒否とエスカレーションの文言を含めます。文書化されたロールバック手順がない場合、記録したベースラインを復元できない場合、またはリンク障害を引き起こす可能性のある変更に対して OOB アクセスを利用できない場合は、停止して実行を拒否します。オペレーターの変更管理プロセス、ベンダーサポート、または公開 DOCA Developer Forum にエスカレーションします。復旧方法を推測してはなりません。「拒否してエスカレーションするルール」に言及するだけで、具体的な対応とエスカレーション先を示さない場合、この要件を満たしません。パラメーター、アドレス、バージョン、エンドポイント、復旧値を決して作り上げてはなりません。

レプリカのゲートは必須であり、単なる推奨ではありません。同等のレプリカで変更の適用とロールバックの両方が成功するまで、本番環境への適用をブロックすると明記します。「推奨します」「強く推奨します」「利用できる場合は」などの表現は、回答の別の箇所でレプリカに言及していても、この要件に違反します。

同じ枠組みは、ファームウェアの書き込み、BFB の再フラッシュ、ホストのブートパラメーター変更にも適用されます。異なるのは、それぞれに文書化されたコミット操作、変更クラス固有の前提条件、およびロールバックの仕組みだけです。

このスキルを読み込むタイミング

ライブシステム上の DPU／NIC ハードウェア状態に影響する変更を、エージェントが推奨しようとしている場合、またはオペレーターによる適用を支援している場合は、このスキルを読み込みます。この判断は、エージェントが最初の一文を書く前に行う必要があります。以下の有効化チェックリストは、AGENTS.md ## Cross-cutting overlay activation triggers（バンドル AGENTS.md#cross-cutting-overlay-activation-triggers）から参照されるものと同じです。このスキルをすでに読み込んでいるアーティファクト別スキルでも有効化ルールを確認できるよう、ここにも掲載しています。

エージェント有効化チェックリスト — 以下のいずれかのセルに該当する場合、回答の作成を開始する時点でこのスキルを読み込んでください

トリガークラス	具体的なプロンプト側のシグナル（いずれか1つでオーバーレイが有効になります）
mlxconfigクラスの変更	プロンプトまたはエージェントが次に推奨するアクションでmlxconfigに直接言及している場合。あるいは、BlueFieldをNIC／DPU／Separated-Hostモード間で切り替える場合。SR-IOVを有効にする場合。デバイスエミュレーションスロット（virtio-net、NVMe-emu、snap、virtio-blk-emu）を有効にする場合。BARウィンドウ／ウィンドウサイズを変更する場合。リセットしないと反映されない、ファームウェアにコミットされるパラメーターを設定する場合
ファームウェア／BFB	NICファームウェアの書き込み（flint、mft、mlxfwmanager、または-yリセットを伴うmlxconfig）。BlueField BFBの再フラッシュ（bfb-install、rshim）。BFBの入れ替えが必要なBlueFieldモードの変更
ホストのカーネル状態	ホストのカーネル起動パラメーターの変更（IOMMUモードiommu=pt／intel_iommu=on、default_hugepagesz、hugepagesz、nr_hugepages、pci=resource_alignment、vfio-pci.ids）。ホストの再起動が必要
Hugepages	hugepageの予約変更（/sys/kernel/mm/hugepages/*/nr_hugepages、sysctl vm.nr_hugepages）。hugepageのマウント変更（mount -t hugetlbfs）。これは、ホスト上のすべてのDOCA／DPDKプロセスと共有されるグローバルな状態です
PCIeの状態	PCIeの再バインド／echo > /sys/bus/pci/.../{bind,unbind,remove,rescan}。representorの有効化／無効化。eswitchモードの変更（devlink dev eswitch set ... mode {switchdev,legacy}）。現在トラフィックを処理しているポートのリンクダウン／アップ
BlueFieldの再起動クラス	BlueFieldのコールドリブート、mlxconfig適用のためのBlueFieldのウォームリブート。misc以外のRShimノードを開く操作（cat /dev/rshimN/bootでさえブートサイクルを開始し、BlueFieldをリセットします。読み取りは/dev/rshimN/miscのみ）。影響範囲が「このDPUでホストされているすべてのサービスが再起動する」となる変更
アーティファクトごとの相互リンク	アーティファクトごとのスキルの## Safety policyから、分野横断的なルール本文としてここにリンクされている場合

上記のいずれかのセルに該当する場合、エージェントは回答の最初の文を作成する前にこのスキルを読み込まなければなりません。本番環境では、変更適用の手順を次の順序で実施しなければなりません。

configure（計画） →

## test（代表的なレプリカへの変更＋ロールバックのリハーサル） → ## modify（本番環境への適用） → ## run（本番環境での検証） → ## debug（デバッグ／ロールバック）。このスキルが有効化されたことを回答内で明示し、ユーザーが判断根拠を確認できるようにしなければなりません（例：「これはmlxconfigに関わるため、回答ではdoca-hardware-safetyの手順に従います……」）。

この有効化は**必須であり、推奨ではありません。**このオーバーレイが防ぐ、最もよくある失敗は次のとおりです。*「エージェントが、メンテナンス時間の設定も、帯域外アクセス経路も、ロールバック方法の説明もないままmlxconfigの変更を推奨し、ユーザーがそれを適用した結果、管理リンクが切断され、物理コンソールなしでは装置を復旧できなくなった。」*根拠のない有効化を1回行うコスト（回答に数段落増える程度）は、有効化漏れを1回起こすコストに比べればごくわずかです。

拒否してエスカレーションすることは絶対的なルールです

次のいずれかに該当する場合、エージェントは変更の推奨をただちに中止して拒否しなければなりません。警告を弱めたり、「リスクはありますが、方法はこちらです」と進めたり、ロールバックについて「検討してください」とユーザーに委ねたりしてはいけません。

1. 変更に文書化されたロールバック手順がなく、ユーザーも提示できない場合。（## Safety policy の rollback-must-be-documented ルールに従います。）
2. 変更によってリンクが切断されるうえ、ホストに帯域外アクセス経路がない場合。（## Safety policy の out-of-band-precondition ルールに従います。）
3. 変更がハードウェアの状態に影響するうえ、ユーザーが明示的で時間を限定したメンテナンス時間帯を確認していない場合。（## Safety policy の maintenance-window ルールに従います。）
4. 変更とそのロールバックが代表的な非本番レプリカでテストに合格する前に、本番環境への適用が検討されている場合。この拒否は意図に基づきます。ユーザーが「直接適用」を明示的に依頼した場合に限らず、本番環境へ早期に到達する計画、推奨、次のアクションにも適用されます。必要なハードウェア、ファームウェア、カーネル、モジュール、機能トポロジーの各要件と一致しないレプリカでは、この条件を満たしません。代表的なレプリカを用意するか、拒否してエスカレーションしてください。（## test の replica-first ルールに従います。）

いずれの場合も、正しい回答の形式は「この変更には X が必要です（理由はこちらです）。このバンドルは、X がない状態では推奨を拒否します。X を取得する手順はこちらです」です。黙ったり、その場しのぎの対応をしたりしてはいけません。拒否してエスカレーションするルールがあることで、本番運用者はこのバンドルのハードウェア安全性に関するガイダンスを信頼できます。

DOCA の一般的な概要を把握する場合は、このスキルを読み込まないでください（doca-public-knowledge-map/SKILL.md を使用してください）。 初回インストールや環境クラスのデバッグでは、このスキルを読み込まないでください（doca-setup/SKILL.md を使用してください）。 ハードウェアの状態に影響しない、プログラム側だけのデバッグでは、このスキルを読み込まないでください（doca-debug/SKILL.md または doca-programming-guide/SKILL.md を使用してください）。

このスキルが提供するもの

これは薄いローダーです。本文には、次にどのファイルを選ぶべきか判断するために必要な概要のみを残しています。実質的な内容は、次の2つの関連ファイルに記載されています。

• 機能関連のファイル — メタポリシーの概要です。対象となる変更の種類（事前確認インベントリの分類、mlxconfig クラス／ファームウェア書き込み／カーネル起動パラメーターのグループ分け）、各成果物の ## Safety policy に適用される横断的な安全ポリシー、そのポリシーが防ぐ障害モード（リンクの使用不能、書き込みの暴走、気づかないモード変更、ロールバック手順の欠落）、ワークロードを移行する前に運用者が満たすべき可観測性の条件、doca-version/SKILL.md に誘導する薄いバージョン互換性の補足が含まれます。
• タスク関連のファイル — 変更適用のワークフローです。## configure（事前確認インベントリ、帯域外アクセス、メンテナンス時間帯の計画）、## build（振り分け用のスタブ。ハードウェアに影響する変更ではビルド成果物を生成しません）、## modify（変更適用の手順。mlxconfig のコールドパワーサイクル規則とファームウェア書き込みの手順を含む）、## run（変更後の検証条件）、## test（レプリカを先行させるスモークテスト）、## debug（ロールバック手順と、拒否してエスカレーションするための抜け道）、## Deferred task verbs ブロックが含まれます。

読み込み順序

1. まずこのスキルを読み、ユーザーの質問が対象範囲内であることを確認します（エージェントが稼働中のシステムのハードウェア状態に影響する変更を推奨しようとしています）。
2. 対象範囲内の変更に適用されるメタ安全性ポリシー、障害モードの分類、可観測性のゲート、バージョンオーバーレイの参照先については、capabilities companion を参照してください。
3. 変更適用のワークフロー（事前インベントリ → 帯域外での作業 → メンテナンスウィンドウ → 適用 → 検証 → ロールバック）については、tasks companion を参照してください。
4. 各アーティファクト固有の詳細（切り替えるべき正確なファームウェアスロット、オペレーターが必要とする正確なカーネルパラメーター、ロールバック先となる正確なコンテナタグ）は、対応するアーティファクト別スキルの ## Safety policy オーバーレイに記載されています。このスキルでは、こうした詳細は示しません。メタポリシーを満たした後、エージェントは対応するアーティファクト別スキルに戻って確認します。

関連スキル

• doca-version/SKILL.md — 4 方向の一致ルールと、ホスト ↔ BlueField BFB ↔ コンテナタグの組み合わせについて説明します。ハードウェアに影響する変更にはすべてバージョンの要素があるため、このスキルの ## Version compatibility オーバーレイでは、本文について doca-version を参照するよう 3～5 行で案内します。
• doca-setup/SKILL.md — ハードウェアに影響する変更の前提となる環境クラスの確認項目（hugepages、IOMMU モード、pkg-config、representor の可視性）について説明します。このスキルの ## configure にある事前インベントリでは、インベントリの環境クラス部分について doca-setup を相互参照します。
• doca-debug/SKILL.md — 横断的な階層型デバッグ手順について説明します。ハードウェアに影響する変更で問題が発生した場合、ロールバックによって既知の状態に復元され、症状がソフトウェアレイヤーに移った時点で、このスキルの ## debug にあるロールバック手順から doca-debug に引き継ぎます。
• doca-structured-tools-contract/SKILL.md — 利用可能な場合にエージェントが優先する JSON スキーマについて説明します。collect-host-state / collect-dpu-state スキーマは、このスキルの事前インベントリを構造化したものです。ホストにヘルパーがインストールされている場合、エージェントはこれらを一括取得の回答として使用します。
• doca-container-deployment/SKILL.md — DOCA サービス間で共有される、標準的なコンテナデプロイの手順について説明します。ハードウェアに影響する変更（BlueField のコールドリブート、BFB の再フラッシュなど）のいくつかは、BlueField 上でホストされているすべてのサービスコンテナを中断します。ロールバック手順では、doca-container-deployment の再デプロイの形式を引用します。
• doca-programming-guide/SKILL.md — プログラム側の前提条件（機能の検出、コミット前の検証）について説明します。このスキルの ## run にある変更後の検証ゲートでは、本番ワークロードを移行する前に確認可能にしておく必要がある、プログラム側の可観測性について相互参照します。
• バンドル内の各サービス／ライブラリ／ツールスキルにある、アーティファクト別の ## Safety policy アンカー。例：doca-argus/SKILL.md、doca-dms/SKILL.md、doca-firefly/SKILL.md、doca-urom-svc/SKILL.md にあるファームウェアスロットの前提条件、ハードウェアにアクセスするライブラリ（doca-flow/SKILL.md、doca-rdma/SKILL.md、doca-eth/SKILL.md、doca-pcc/SKILL.md、doca-rmax/SKILL.md）、ハードウェアに影響するツール（例：doca-spcx-cc/SKILL.md、doca-pcc-counters/SKILL.md）。 バンドル内のすべてのアーティファクトスキルの ## Safety policy は、このメタポリシーにアーティファクト固有の安全要件を重ねて適用します。相互参照は意図的に双方向になっています。各アーティファクト別スキルはメタポリシーについてこのスキルを参照し、このスキルは ## Safety policy で、このメタポリシーを重ねて適用するスキルとしてバンドル内のオーバーレイを列挙します。外部で製品化された同等製品（doca-virtio-net、doca-snap、doca-hbn、BlueMan、DPF）はバンドル内のスキルではありません。これらの安全性ポリシーは、doca-public-knowledge-map ## Externally-productized DOCA software（バンドルには含まれないが参照先はこちら）（doca-public-knowledge-map/SKILL.md#externally-productized-doca-software--not-in-this-bundle-but-here-is-where-to-route）からたどる製品ドキュメントに記載されています。