From 0355c73211e679493ce25c09552cff638ec6d8e2 Mon Sep 17 00:00:00 2001 From: Raphael Maenle Date: Tue, 9 Jun 2026 23:23:42 +0200 Subject: [PATCH] docs: refresh stale file paths after store/ reorg + gen_messages rename MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit generate_messages.py → gen_messages.py and several gem/ headers moved under gem/store/ (carrier_store.hpp → store/carriers.hpp, etc.); e84.hpp split into e84_state.hpp. The guided-tour chapters still pointed at the old paths — relink them so the deep-link footnotes resolve. Co-Authored-By: Claude Opus 4.7 --- docs/00_index.md | 2 +- docs/01_what_is_secs_gem.md | 2 +- docs/02_the_cast.md | 9 ++++---- docs/03_vocabulary_and_a_wafers_journey.md | 26 +++++++++++----------- docs/17_e116_e120_e39_objects.md | 2 +- docs/30_repository_tour.md | 4 ++-- docs/40_building_running_demo.md | 6 +++-- 7 files changed, 26 insertions(+), 25 deletions(-) diff --git a/docs/00_index.md b/docs/00_index.md index 9822917..cbe53a6 100644 --- a/docs/00_index.md +++ b/docs/00_index.md @@ -122,7 +122,7 @@ extension points spelled out. | # | Title | Covers | |---|-------|--------| | [30](30_repository_tour.md) | Repository tour | Directory layout, build system, the eight apps, the test suite. | -| [31](31_spec_as_data_and_codegen.md) | Spec-as-data + codegen | The five YAML files, how `tools/generate_messages.py` turns `messages.yaml` into typed C++. | +| [31](31_spec_as_data_and_codegen.md) | Spec-as-data + codegen | The five YAML files, how `tools/gen_messages.py` turns `messages.yaml` into typed C++. | | [32](32_stores_and_the_data_model.md) | Stores + the data model | `EquipmentDataModel`, every per-domain store (SVIDs, alarms, carriers, substrates, …) and how they compose. | | [33](33_transport.md) | Transport | `hsms::Connection` (asio TCP) and `secsi::Protocol` (FSM-only); the strand-threading contract; T-timer wiring. | | [34](34_codec_and_sml.md) | Codec + SML | `secs2::Item` variant, `encode`/`decode`, the SML parser and printer, the identifier-wildcard rule. | diff --git a/docs/01_what_is_secs_gem.md b/docs/01_what_is_secs_gem.md index 0edfdcd..f92665b 100644 --- a/docs/01_what_is_secs_gem.md +++ b/docs/01_what_is_secs_gem.md @@ -237,7 +237,7 @@ layer (`secs2`) which is moved by the transport layer (`hsms` or The **codegen** row is worth a footnote: SECS-II has ~160 named messages and each one has a typed struct body. Writing all 160 builders + parsers by hand would be 5000+ lines of boilerplate, so -`tools/generate_messages.py` reads `data/messages.yaml` at build time +`tools/gen_messages.py` reads `data/messages.yaml` at build time and emits `messages.hpp` with one typed struct + builder + parser per message. Chapter [31](31_spec_as_data_and_codegen.md) walks through how it works. diff --git a/docs/02_the_cast.md b/docs/02_the_cast.md index 4c22db5..e5a4543 100644 --- a/docs/02_the_cast.md +++ b/docs/02_the_cast.md @@ -290,11 +290,10 @@ substrate. **Where it lives in this codebase.** -- The E84 handshake state machine: [`include/secsgem/gem/e84.hpp`](../include/secsgem/gem/e84.hpp) - + [`src/gem/e84.cpp`](../src/gem/e84.cpp). -- The TA1/TA2/TA3 timer wiring: [`include/secsgem/gem/e84_timers.hpp`](../include/secsgem/gem/e84_timers.hpp), - [`include/secsgem/gem/e84_asio_timers.hpp`](../include/secsgem/gem/e84_asio_timers.hpp). -- The per-port store: `e84_ports.hpp` (see [`include/secsgem/gem/e84_ports.hpp`](../include/secsgem/gem/e84_ports.hpp)). +- The E84 handshake state machine: [`include/secsgem/gem/e84_state.hpp`](../include/secsgem/gem/e84_state.hpp) + + [`src/gem/e84_state.cpp`](../src/gem/e84_state.cpp). +- The TA1/TA2/TA3 timer wiring (asio): [`include/secsgem/gem/e84_asio_timers.hpp`](../include/secsgem/gem/e84_asio_timers.hpp). +- The per-port store: [`include/secsgem/gem/store/e84_ports.hpp`](../include/secsgem/gem/store/e84_ports.hpp). - Tests covering the timing rules: [`tests/test_e84.cpp`](../tests/test_e84.cpp), [`tests/test_e84_timers.cpp`](../tests/test_e84_timers.cpp), [`tests/test_e84_asio_timers.cpp`](../tests/test_e84_asio_timers.cpp), diff --git a/docs/03_vocabulary_and_a_wafers_journey.md b/docs/03_vocabulary_and_a_wafers_journey.md index 3f3a67f..ad52b51 100644 --- a/docs/03_vocabulary_and_a_wafers_journey.md +++ b/docs/03_vocabulary_and_a_wafers_journey.md @@ -111,8 +111,8 @@ Any of these timing out → both sides go to `HandoffFault` and the operator gets paged. No FOUP gets dropped because the protocol guarantees both sides agreed on every step. -**Where:** [`include/secsgem/gem/e84.hpp`](../include/secsgem/gem/e84.hpp) -defines the FSM; [`include/secsgem/gem/e84_timers.hpp`](../include/secsgem/gem/e84_timers.hpp) +**Where:** [`include/secsgem/gem/e84_state.hpp`](../include/secsgem/gem/e84_state.hpp) +defines the FSM; [`include/secsgem/gem/e84_asio_timers.hpp`](../include/secsgem/gem/e84_asio_timers.hpp) defines the timer enforcement; chapter [18](18_e84_parallel_io.md) walks the whole handshake. @@ -164,7 +164,7 @@ Note the pattern: every primary message ends in an odd function This is invariant across SECS-II. See chapter [10](10_e5_secs_ii_data_items.md) for the encoding details. -**Where:** `gem::CarrierStore` in [`include/secsgem/gem/carrier_store.hpp`](../include/secsgem/gem/carrier_store.hpp); +**Where:** `gem::CarrierStore` in [`include/secsgem/gem/store/carriers.hpp`](../include/secsgem/gem/store/carriers.hpp); the E87 wire tests in [`tests/test_e87_wire_scenarios.cpp`](../tests/test_e87_wire_scenarios.cpp). --- @@ -234,8 +234,8 @@ New acronyms: E40 governs process jobs; E94 governs control jobs above them. -**Where:** [`include/secsgem/gem/process_jobs.hpp`](../include/secsgem/gem/process_jobs.hpp), -[`include/secsgem/gem/control_jobs.hpp`](../include/secsgem/gem/control_jobs.hpp). +**Where:** [`include/secsgem/gem/store/process_jobs.hpp`](../include/secsgem/gem/store/process_jobs.hpp), +[`include/secsgem/gem/store/control_jobs.hpp`](../include/secsgem/gem/store/control_jobs.hpp). The state machines are loaded from [`data/process_job_state.yaml`](../data/process_job_state.yaml) and [`data/control_job_state.yaml`](../data/control_job_state.yaml). @@ -295,8 +295,8 @@ same value, but each one has its own enumeration of failure codes (`3 = at least one CEID does not exist`, etc.). Don't reuse one stream's enum for another's. -**Where:** [`include/secsgem/gem/report_store.hpp`](../include/secsgem/gem/report_store.hpp), -[`include/secsgem/gem/event_store.hpp`](../include/secsgem/gem/event_store.hpp). +**Where:** [`include/secsgem/gem/store/event_reports.hpp`](../include/secsgem/gem/store/event_reports.hpp) +(reports + collection events live together — the same store backs S2F33/F35/F37). The configuration flow is the heart of E30 §6.6 Dynamic Event Report Configuration; see chapter [13](13_e30_gem.md). @@ -346,8 +346,8 @@ The `S6F11(CEID=300)` that fires next is the event report (If CEID 300 had been left *disabled*, the processing logic would still fire it but the wire would stay quiet.) -**Where:** [`include/secsgem/gem/host_command_registry.hpp`](../include/secsgem/gem/host_command_registry.hpp) -maps `RCMD` strings to handlers; the report-emission machinery lives +**Where:** [`include/secsgem/gem/store/host_commands.hpp`](../include/secsgem/gem/store/host_commands.hpp) +(`HostCommandRegistry`) maps `RCMD` strings to handlers; the report-emission machinery lives in `EquipmentDataModel` ([`include/secsgem/gem/data_model.hpp`](../include/secsgem/gem/data_model.hpp)) via `compose_reports_for(ceid)`. Wire-level tests: [`tests/test_wire_ceid_emission.cpp`](../tests/test_wire_ceid_emission.cpp). @@ -391,9 +391,9 @@ When the pressure returns to range, a second `S5F1` fires with `ALCD=0x04` (bit 7 cleared) and the same ALID, signalling "alarm cleared." -**Where:** [`include/secsgem/gem/alarm_store.hpp`](../include/secsgem/gem/alarm_store.hpp); -the dispatcher gates emission on the enable list in -[`include/secsgem/gem/alarm_dispatcher.hpp`](../include/secsgem/gem/alarm_dispatcher.hpp). +**Where:** [`include/secsgem/gem/store/alarms.hpp`](../include/secsgem/gem/store/alarms.hpp) +defines `AlarmRegistry`, which both stores the definitions and gates +S5F1 emission on the enable list. --- @@ -564,7 +564,7 @@ The streams you'll meet most often, with one sentence each: Where every named message lives in code: [`build/generated/secsgem/gem/messages.hpp`](../build/generated/secsgem/gem/messages.hpp) (after a build) — generated from [`data/messages.yaml`](../data/messages.yaml) by -[`tools/generate_messages.py`](../tools/generate_messages.py). +[`tools/gen_messages.py`](../tools/gen_messages.py). Chapter [31](31_spec_as_data_and_codegen.md) walks the codegen. --- diff --git a/docs/17_e116_e120_e39_objects.md b/docs/17_e116_e120_e39_objects.md index 18f4952..24821b4 100644 --- a/docs/17_e116_e120_e39_objects.md +++ b/docs/17_e116_e120_e39_objects.md @@ -196,7 +196,7 @@ Alarm attribute, or a Process Module attribute. ### Code Handlers live in -[`include/secsgem/gem/host_command_registry.hpp`](../include/secsgem/gem/host_command_registry.hpp) +[`include/secsgem/gem/store/host_commands.hpp`](../include/secsgem/gem/store/host_commands.hpp) and the generated message catalog. Tests are bundled into diff --git a/docs/30_repository_tour.md b/docs/30_repository_tour.md index 6c83888..26f8404 100644 --- a/docs/30_repository_tour.md +++ b/docs/30_repository_tour.md @@ -67,7 +67,7 @@ secs-gem/ │ └── equipment.yaml Demo SVIDs/ECIDs/CEIDs/alarms/recipes. │ ├── tools/ Build-time scripts. -│ └── generate_messages.py Codegen: messages.yaml → messages.hpp. +│ └── gen_messages.py Codegen: messages.yaml → messages.hpp. │ ├── interop/ External-validator harnesses. │ ├── README.md Harness-by-harness detail. @@ -171,7 +171,7 @@ included. 1. **Pull in dependencies** — `find_package(Threads)`, `find_package(yaml-cpp)`, `FetchContent` for doctest. Standalone Asio is header-only (no link step). -2. **Run codegen** — invokes `tools/generate_messages.py` to turn +2. **Run codegen** — invokes `tools/gen_messages.py` to turn `data/messages.yaml` into `build/generated/secsgem/gem/messages.hpp`. Listed as a custom command so it re-runs when `messages.yaml` changes. diff --git a/docs/40_building_running_demo.md b/docs/40_building_running_demo.md index 3746241..b508a8e 100644 --- a/docs/40_building_running_demo.md +++ b/docs/40_building_running_demo.md @@ -319,8 +319,10 @@ docker compose run --rm builder tshark -i any -d "tcp.port==5000,hsms" -V \ `pvd_tool` example exposes a Prometheus endpoint: ```bash -docker run --rm -p 9090:9090 pvd_tool /app/examples/pvd_tool/equipment.yaml \ - /app/data/control_state.yaml 5000 9090 +docker compose run --rm --service-ports builder /app/build/pvd_tool \ + /app/examples/pvd_tool/equipment.yaml \ + /app/data/control_state.yaml \ + 5000 9090 ``` Then `curl localhost:9090/metrics`.