共通基盤の機能・動作仕様¶
文書バージョン：1.1.0
対象GitHubバージョン：main @ c67e153cc3bcf1f6ac0303d23023ce8ae4a4f533
収録リリース：v1.1.6（本文・画像の調査基準は上記commitを維持）
追補：2026-10-17 Timer通知APIの修正差分（v1.1.6収録の追補）。基準版・画像の取得条件は維持。
文書ID：guide-reference-core
文書状態：現行実装の調査に基づく仕様検討用資料。正式な契約の変更は参照先の詳細仕様で行う。
更新履歴¶
| 文書バージョン | 更新日 | 更新内容 |
|---|---|---|
1.1.0 |
2026-10-17 |
初版。入力、実行、資源、計測、結果、拡張APIを機能と動作の組で整理。v1.1.6へ収録し、本文・画像の調査基準を維持 |
全体の入口に、読み方・用語・対象profileの一覧がある。本章の「固定」は、この基準コミットの利用者向け設定に選択肢がないという意味であり、将来変更できないという意味ではない。
CLIとライブラリによる準備・実行¶
概要¶
機能仕様： 構造を表すNED、条件を表すINI、モデル構成と負荷を表すJSONから実験を実行する。入力だけの検証、結果の保存、Viewer生成を別操作として提供する。GUIを使わず同じ入力を繰り返し実行できる。
動作仕様： validateで入力を検査し、runで仮想時刻を進めて結果を保存し、viewで保存結果からHTMLを生成する。validate成功だけではイベント実行・出力先への書き込み・モデルの全動作が成功したとはいえない。
詳細¶
機能仕様： CLIの入口は次の通り。モデル条件はINIへ置き、CLIとの二重指定を避ける。
| 操作 | 必須入力／出力 | 変更可能な場所・固定条件 |
|---|---|---|
validate --config PATH |
INI。成功時はJSONの検証要約 | configは起動ディレクトリから解決。未知・重複オプションを拒否 |
run --config PATH --output DIR |
INI、新規または空の結果ディレクトリ | 出力名はCLIで選ぶ。親ディレクトリは既存。既存結果の上書きは提供しない |
view --input results.json --output viewer.html |
保存JSON、新規HTML | 既存HTMLの上書きを拒否。生成後のブラウザ起動は利用者が行う |
ned-editor [--config PATH] [--export-root DIR] [--state-root DIR] |
省略時は新規プロジェクトから開始 | 詳細は画面編 |
--version |
Cargoパッケージ版を表示 | 基準ソースは0.1.0。Gitタグv1.1.5や文書版とは別の番号 |
動作仕様： 入力取得→解析・解決→モデル固有検証→実行準備→イベント処理→終了処理→結果公開となる。Rustのprepare／runとrun_configも利用できる。組込みCANは専用Engine、任意登録モデルはfactory・callbackを使う経路であり、同一API名から内部経路の同一性を推測しない。組込みprofileをprepare_with_registryで選んでも、通常の組込みadapterから専用エンジンへ委譲する経路がある。run_with_diagnosticsは二次診断を含む失敗情報を扱う。
cargo build --locked -p dir-simulator
./target/debug/dir-simulator validate --config examples/guide/can/minimal.ini
./target/debug/dir-simulator run --config examples/guide/can/minimal.ini --output results-reference
./target/debug/dir-simulator view --input results-reference/results.json --output reference-viewer.html
出力名は未使用の名前へ変える。動作確認の対象環境はWSL上のUbuntu 24.04 LTS x86_64。Rust edition 2024／1.85.0を基準とし、Windows nativeでの同一動作は本資料の確認範囲に含めていない。
変更判断： バッチ実行、自動比較、複数実験の管理はCLIを外側から呼ぶ形で実現できる。CLI引数の追加は入力優先順位、ライブラリとの整合、終了コードを併せて決める。
参照：インタフェース仕様、公開API、CLI実装、利用フロー検証仕様。
NEDによる型・階層・接続の定義¶
概要¶
機能仕様： 部品型、配置した実体、接続点、通信経路をテキストで定義する。同じ型を複数箇所で再利用し、複合部品で階層化できる。
動作仕様： ned-pathの下からNEDを収集し、package・型・実装登録・接続を検査する。選択したnetworkを展開して実体を作る。探索範囲にある未使用型も構文等の検査対象なので、使っていない不正なNEDが準備失敗の原因になることがある。
詳細¶
機能仕様： simpleは振る舞いのある部品、moduleは子を持つ複合部品、networkは実験の起点、channelは接続上の処理を表す。@classはコンパイル済みRust実装への対応であり、NEDだけで新しい処理アルゴリズムを作るものではない。
| 指定 | 場所／単位／既定 | 固定条件・変更の影響 |
|---|---|---|
network |
INI [General]、完全修飾型名、必須 |
root実体名は型名の末尾。変更すると実体path参照も変わる |
ned-path |
INI、引用したディレクトリを;区切り、必須 |
configの親が相対パス基準。重複・包含するroot、symlinkは拒否 |
package |
各NED、ディレクトリと一致 | 型参照は完全修飾名。大小文字を区別 |
parameters |
NED、int/double/bool/string |
値のdefaultと実装スキーマを照合。親parameterを子へ暗黙転送しない |
gates |
NED、scalar input/output |
vector、inoutは未対応 |
connections |
NED、a.tx --> b.rx;等 |
各simpleポートは一接続。compound境界の内外を別々に検査 |
@class("...") |
simple/channelのparameters節 | 実装キー、パラメータ集合、port schemaの一致が必要 |
@display／@description |
型やparameterの属性 | メタデータとして保持。任意のOMNeT++表示文字列の再現を約束しない |
動作仕様： 未知型、重複定義、包含循環、方向不一致、未接続、protocol/message/schema版不一致を拒否する。compoundのinputは内部では始点、outputは内部では終点になる。channelを通る複数辺は別の実体として保持する。
DIRはNEDの限定した文法を独自に解釈する。import、extends、条件／ループ、式、動的接続、双方向矢印、vectorは現行入力で拒否する。OMNeT++のNEDを無変更で読み込めるという互換性はない。NEDの由来・本来の階層とsimple/module/channelの関係はOMNeT++公式マニュアルを参照する。
変更判断： 部品追加・結線変更はNEDで行える。接続数制限や型の再利用方式を変える場合は、共通文法だけでなく各profileのvalidatorとNEDエディタの編集能力も変更対象になる。
参照：NED仕様、入力設計、NED parser、入力検証仕様。
INI・JSONによる条件指定と単位換算¶
概要¶
機能仕様： 同じ構造のまま速度、容量、遅延、実行期間、負荷を変えて比較する。値がNEDのdefaultかINIの上書きかを追跡できる。
動作仕様： NED宣言と登録スキーマを照合し、INIの指定を優先して値を確定する。指定がなければNED defaultを使い、どちらもなければ必須値欠落とする。JSONの配列・表の意味は選択profileが検査する。
詳細¶
機能仕様： 共通の主要設定は次の通り。「省略可」は全入力を省略できる意味ではない。
| キー | 場所 | 必須／既定 | 単位・値域／固定条件 |
|---|---|---|---|
sim-time-limit |
INI [General] |
必須 | 0以上、整数psに正確換算できる時間 |
metrics-window |
同上 | 1ms |
正の整数ps、窓集計幅 |
max-events |
同上 | 100000000 |
1～u64最大の十進整数 |
max-delta-cycles |
同上 | 1000000 |
1～u64最大。同時刻反復の上限 |
model-profile |
同上 | "can.cc.ideal.v1" |
基準commitの入口に記載した16 profileから一つを選択 |
model-config |
同上 | 追加profileでは必要 | 引用JSONパス。具体の必須性・形状はモデル章を参照 |
workload |
同上 | 省略時は空の負荷集合 | 指定時は実在するファイル。profileによってschema/kindが異なる |
Main.a.queueCapacity等 |
同上 | 同じ対象のNED defaultを上書き | 実体の完全path。wildcardは使えない |
delay等 |
[Channel Main::a.tx] |
当該辺のchannel default | 接続識別は親path＋::＋始点。辺ごとに独立 |
動作仕様： 相対参照はINIの親ディレクトリ基準。取得した入力snapshotを実行に使用する。上書きで隠れたNED defaultも型・単位・値域の検査対象になるため、不正defaultをINIで覆って回避はできない。未知・重複キー、未知節、include、環境変数展開、行末コメント、式は拒否する。コメントは独立した行に書く。
| 量 | 受理する単位 | 誤読しやすい点 |
|---|---|---|
| 時間 | ps ns us ms s |
1ns=1000ps。0.001nsは1ps、0.1psは拒否。µsではなく入力はus |
| 速度 | bps kbps Mbps Gbps |
0.5Mbps=500000bps。大文字小文字を区別 |
| データ量 | B kB MB GB KiB MiB GiB |
1kB=1000B、1KiB=1024B。bitとbyteを混同しない |
| 件数・整数 | 単位なし | intに64.0や0x40を指定しない。u64実行上限は通常のNED intと別の範囲 |
時間・量は十進数から正確な整数へ換算する。指数記法、NaN、Infinity等を受理しない。モデル固有のJSONが文字列整数を要求する項目では、"10"とJSON numberの10を交換しない。
変更判断： 値の変更、defaultの変更、入力形式の変更を分ける。新単位・wildcard・式を追加するなら、parserだけでなく出典情報、エラー位置、エディタの一括変更、再現性hashも確認する。
参照：設定仕様、入力実装、入力設計。JSON形式自体はRFC 8259、ps等の接頭語はBIPM SI Brochureを参照する。採用単位の集合はDIRの仕様である。
仮想時刻・同時刻順序・終了¶
概要¶
機能仕様： 通信・処理・解放を離散イベントとして実行し、同じ条件から同じ処理順と結果を得る。仮想時刻と処理にかかった実時間は別々に扱う。
動作仕様： 次のイベント時刻へ進み、その時刻の完了・入力・調停を所定順に処理する。観測期間は[0,T)で、Tちょうどのイベントは実行しない。Tまでの正常終了でも、送信中・待機中の要求が残ることがある。
詳細¶
機能仕様： 時刻はu64の整数ps。0～18446744073709551615psを表現する。物理転送時間はビット数N・速度Rに対しceil(N×10^12/R)psを基本にモデル側で算出する。丸め位置はモデル仕様に従う。
| 項目 | 選択・設定 | 固定動作と変更影響 |
|---|---|---|
| 仮想終了時刻 | INI sim-time-limit |
Tは含まない。境界を変えると全profileの結果が変わる |
| イベント順 | 利用者設定なし | (time_ps, delta, phase, sequence)順 |
| phase | 利用者設定なし | 0=完了・解放、1=入力・配送・Timer、2=調停 |
| 同時刻反復 | INI max-delta-cycles |
前のphaseへの予約は次delta。deltaは物理時間ではない |
| 全イベント上限 | INI max-events |
上限まで許可し、次の有効イベントを実行する前に停止 |
| 乱数 | profile固有のseedがある箇所だけ | 共通基盤が全モデルへ確率ノイズを加える機能ではない |
動作仕様： 解放が100us、A/Bのreadyも100usなら、解放→両者の受付→調停の順になる。phase 2でAの送信が確定した後にBが来ても、通常の非プリエンプトモデルではAを継続する。通常終了で10usにイベントが尽きT=1msなら、観測の分母は1ms、最後のイベント時刻は10usになる。T=0は入力検証と初期化を行うがイベント処理は0件。
過去時刻への予約、時刻／連番のoverflow、上限超過は診断付きで停止する。上限を大きくしてもモデルの無限ループが修正されるわけではない。
変更判断： 実験期間は設定で調整する。Tを含む終了、同時刻優先順、同期クロック、途中再開を変える場合は共通実行・各モデル・集計窓・Viewerをまとめて見直す。
参照：実行仕様、実行設計、scheduler実装、共通実行検証仕様。
有限資源と要求の受付¶
概要¶
機能仕様： 送信キューや共有資源に容量・競合を持たせ、待ち時間と破棄を評価する。
動作仕様： 受付時点の使用量を確認し、空きがあれば保持し、満杯ならモデルの方針に従って破棄・待機・full応答を返す。容量を「処理中を含めるか」はモデルごとに異なる。
詳細¶
機能仕様： 共通資源仕様のCAN TXキューはqueueCapacityで待機フレーム数を制限する。NED配布例のdefaultは64、範囲0～4294967295。処理中・送信中・受信処理中はこの待機数に含めない。
動作仕様： ready時に満杯なら新着をdrop-newestで破棄し、調停で勝ったSOF時に取り出す。同じ時刻でも受付がphase 1、取り出しがphase 2なので、「この後送る予定」があっても受付時に満杯なら破棄する。容量0は空きバスへの直送にもならない。
| 他モデルとの相違 | 読む先 |
|---|---|
| GatewayのRX保持とTX待機は別容量・別状態 | CAN・Gateway編 |
| Ethernetは出力キュー・優先クラス・copyごとの扱い | Ethernet編 |
| AXI/SoCのpending＋active、メモリ待機キューとactiveの分離 | SoC・メモリ・IPC編 |
変更判断： drop-oldest、送信中を含む容量、byte単位の制限、backpressureへの変更は、数値変更とは別の仕様変更。キューの長さの計測と保存則、同時刻境界も更新する。
参照：資源仕様、CAN runtime、各モデル章の設定表と検証先。
計測・集計と結果の読み方¶
概要¶
機能仕様： 要求ごとの経過、時系列の使用量、窓ごとの指標、実験全体の集計を保存する。
動作仕様： 到達した時点だけを実績として記録し、点の平均と時間平均を分ける。完了しなかった要求を成功数や完了遅延へ混ぜない。平均の分母が0ならnullになる指標がある。
詳細¶
機能仕様： metrics-windowは窓幅で、実行時刻の分解能は変更しない。CANを例にした主要な意味は次の通り。
| 指標／状態 | 算出するもの | 読み違えを避ける条件 |
|---|---|---|
tx_wait_ps |
生成→SOF | TX処理と競合待ちを含む |
arbitration_wait_ps |
readyまたは実TX受理→SOF | Gatewayの待機では実受理時刻が別にある |
| 転送時間 | SOF→実EOF | planned EOFだけでは完了標本にならない |
| 配送遅延 | 生成→受信完了 | 受信者別。送信成功と全受信先完了は別 |
| キュー平均 | 使用量の時間積分÷観測長 | イベント発生時の単純平均と異なる |
| バス使用率 | 定義された占有期間÷観測長 | CANのframe占有とintermission込み占有を分ける |
unfinished |
終了時に未完了の要求 | 正常time_limitでも0になるとは限らない |
動作仕様： 窓は左端を含み右端を含まない。終端と同じ時刻の点標本は次の窓側で扱う。正常イベント枯渇でもTまでのアイドル時間を積分する。実行失敗の結果は直前までにコミットされた処理のprefixであり、同時刻の未処理イベントが残り得る。異常結果と正常runの平均を無条件に比較しない。
組込みprofileの指標名・単位・record schemaはmetadataのcatalogとモデル仕様に対応する。既存MetricDescriptorの名前・単位・u64点観測は維持する。現行ソースでは別登録の整数Metric V2を追加し、point/gaugeと指定した平均・窓集計を提供する。histogramや任意集計器を自由定義するAPIではない。現行利用境界を参照。
変更判断： 平均の母数、締切の起点、失敗要求の扱い、利用率に含む区間を先に決める。表示名だけを変更して同じmetric IDの意味を変えると過去結果との比較を誤るため、metricの版とViewerの対応を検討する。
参照：結果仕様、結果設計、出力実装、結果検証仕様。実画面はViewerの説明に掲載。
結果の公開・入力出典・再現性¶
概要¶
機能仕様： JSON/CSV、診断、入力出典を組にして保存し、どの入力・実装から得た結果かを確認できる。
動作仕様： ファイルを書き終えてhashを計算し、最後にmanifestを公開する。manifestのcompleteはファイル集合の公開完了を示す。シミュレーションの正常終了はterminationとpartialを別に確認する。
詳細¶
機能仕様： CLI結果の基本集合は次の5ファイル。
| ファイル | 内容 | 編集・拡張時の注意 |
|---|---|---|
results.json |
metadata、実行状態、台帳、時系列、集計 | 結果の正本。全時刻・件数等の大整数は十進文字列 |
events.csv |
計測の時系列 | 全ての内部イベントを逐一説明する実行ログではない |
summary.csv |
全体の計測集計 | JSONと同じ意味・単位で対応する |
diagnostics.jsonl |
構造化診断、正常なら空 | 空ファイルもmanifest対象 |
manifest.json |
他4ファイルのbytes・SHA-256、終了状態、metadata参照 | 自分自身をhash一覧へ含めない |
動作仕様： schema1のCANはsimulation.requests/receiversを持つ。schema2の追加profileはmodel_records/metric_records等の契約に従う。同じ「要求」を探す場合もprofile/schemaを確認する。入力snapshot・hash・解決値・runtime/build情報は結果と対応付く。simulationの決定性と、run ID、保存パス、実時間、OS診断を含むファイル全体のbyte一致は別の比較である。
書込みやhash計算に失敗しmanifestが公開されていなければ完成結果として扱わない。NEDエディタのrun管理では、この5ファイルの周囲に固定入力・実行状態・Viewer等も管理するが、CLIの結果形式と同一ディレクトリ契約だと推測しない。
変更判断： 結果を外部ツールへ渡す場合、列・型・null・schemaの互換性を確認する。秘密を含む入力を実行するとsnapshotやViewerにも含まれ得るため、配布用結果は公開可能な入力から作る。
診断と異常時の停止¶
概要¶
機能仕様： 不正入力、実行中の失敗、出力の失敗を区別し、対象と原因を機械処理できる形式で返す。
動作仕様： 入力不正ならイベント実行前に止まり、実行不正なら確定済み部分の出力を試みる。強制kill等では後処理を保証できないため、結果の完成判定にmanifestを使う。
詳細¶
機能仕様： 次の終了コードは固定。自動化では日本語／英語の説明文ではなくcode/reason/terminationを判定する。
| CLI exit | 主な状態 | 次の判断 |
|---|---|---|
| 0 | time_limit／events_exhausted、validate成功 |
unfinishedや期待した配送先を別途確認 |
| 2 | prep_failed、E-0001 |
入力位置、未知キー、schema、接続を修正 |
| 3 | execution_failed、E-0002/E-0004 |
モデル失敗、上限、overflow等を確認 |
| 4 | output_failed、E-0003 |
空き容量・権限・出力先状態を確認。先行の実行失敗も保持 |
動作仕様： 最初の不正がprimaryで、終了処理や出力中の失敗はsecondary。入力の行列は1起点でUnicode scalar単位、TABも1列として数える。通常のprepareは最初の不正で停止するため、一つ直した後に別のエラーが現れる場合がある。実行中のcallback失敗では未確定の効果を公開せず全体を止めるが、任意モデル内部の状態を元に戻して再実行する仕組みではない。
変更判断： エラーの無視・警告化、再試行、部分結果からの再開を導入する場合は失敗モデルの状態、保存台帳、外部副作用を含む契約が必要。単に終了コードを0へ変えることは成功条件の追加にならない。
Rust登録APIによるモデル拡張¶
概要¶
機能仕様： 静的リンクしたRustのmodule/channel、event schema、profile、codec、metricを登録し、独自モデルを同じ入力・実行・出力の流れへ接続する。
動作仕様： RegistryのdescriptorとNEDの宣言を照合して実体を生成し、initialize→on_event→finishを呼ぶ。Contextの予約・配送・取消・観測はcallback単位の効果として確定する。
詳細¶
機能仕様： prepare_with_registry／run_config_with_registryへRegistryを渡す。既存CLIへJSONを書くだけで新しいRust実装を注入する機能ではなく、利用側のRustビルドが必要。
| 変更項目 | 場所 | 固定契約・検討事項 |
|---|---|---|
| NED対応実装 | register_module／register_channel |
実装キー、parameter/port schema、factoryを揃える |
| イベント | register_event、Schema、Envelope |
名前・版・payload validator・phase。未知schemaを拒否 |
| profile | register_profile |
必要実装・event・codec等の参照を準備時照合 |
| 観測 | MetricDescriptor／Contextの観測 |
legacyは名前・単位・u64点値。別登録の整数Metric V2は現行限定実装・schema3 |
| Timer | schedule_at／schedule_after／current_timer_token／cancel |
予約tokenの所有者と取消状態を管理。発火中tokenは公開読取APIで取得 |
動作仕様： 初期化後にだけイベント処理へ入り、callback成功と検証成功で効果を一括確定する。別所有者・実行済み・取消済みtokenの取消しはfalseとなる。finishからの新規イベントや観測追加は認めない。
2026-10-17追補・修正済み（v1.1.6収録）： 調査基準c67e153には「token付きで通知」と公開APIの不一致があった。本作業の差分ではContext::current_timer_token()を追加し、Timerのon_eventから予約時と等しいtokenを取得できる。同じ時刻・schema・payloadのTimerも返却tokenで区別できる。initialize・ポート配送・on_arbitrationではNoneであり、発火中・発火済みtokenのcancelはfalseのままである。Envelopeとtokenの非公開fieldは維持する。この追補は基準コミットや既存タグへ遡及した説明ではない。
// Model::on_event内。予約時のtokenをselfへ保存しておく。
if let Some(token) = context.current_timer_token().cloned() {
// tokenと保存済み予約tokenを比較して発火したTimerを判別する。
assert!(!context.cancel(&token)); // 現在発火中のTimerは取消せない。
}
変更判断： 拡張APIの使いやすさを評価する際は、組込み専用エンジンの成功だけで任意モデルのcallback経路を評価しない。Timer通知の修正・検証範囲と、実装済み限定scopeの独自指標・協調制御・generic checkpointは変更検討台帳で区別する。
参照：インタフェース仕様、実行仕様、Registry実装、汎用runtime、Registry試験。
2026-10-17現行実装追補：承認済み後続10分野のAPI・設定・scope・出力・Viewer境界を追加した。固定commitに基づく既存画像・実測は取得時の証跡として保持する。新機能はv1.1.6に収録する。製品受入最終判定は同追補の製品検証記録へ分離する。文書版・履歴は本pushの改訂として確定した。