docs: worked PVD-tool vendor example

A fictional Physical Vapor Deposition tool wired end-to-end. examples/pvd_tool/ is the template a real customer should fork. Files: - equipment.yaml: 32 SVIDs (chamber pressure, temperature, source power, gas flows, cooling water, wafer counters, recipe step state, EPT name, 4 load ports), 5 DVIDs, 7 ECIDs (setpoints + T_CRA/T_DELAY + cleaning interval + retry count), 17 CEIDs (control state, alarms, process lifecycle, material movement, EPT), 12 alarms with realistic categories (safety, error, warning, attention), 3 multi-step recipes (Al / Ti / Cu), 9 host commands. - main.cpp (~860 lines): the vendor-side application: §1 helpers + constants §2 sensor simulator — 4 sensors at 10 Hz + 1 Hz cadences, random-walk around step-targeted setpoints, asio::post-on-strand thread-safety pattern §3 recipe runner — parses recipe body (STEP NAME duration=120s power=2500W gas=Argon flow=50sccm), walks each step at 1s per declared-second, fires step-started/completed CEIDs, drives PJ FSM through ProcessComplete §4 alarm threshold monitor — chamber-pressure-over-setpoint and cleaning-interval logic, continuous evaluation, set/clear emission gated on alarm-enable §5 EPT cycler — Standby ↔ Productive ↔ UnscheduledDowntime based on PJ activity + safety alarms §6 Prometheus exporter on :9090 (pvd_messages_total, pvd_chamber_pressure_torr, pvd_spool_depth, pvd_events_total, pvd_alarm_set_total) §7 Router handlers — full E30 set (~40 handlers) so a host can do real work §8 main() — YAML validation, model construction, server wiring, periodic gauge updates - README.md: section-by-section walkthrough, what's the same as apps/secs_server.cpp, what this adds (simulator + recipe runner + alarm monitor + EPT cycler + metrics), what's not here (persistence + E84 + real I/O), and what to change for your tool. Verification: 47/47 conformance harness checks PASS against the PVD tool — same as the demo server. CMakeLists.txt adds the pvd_tool target. README's documentation map points at examples/pvd_tool/. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-09 16:57:10 +02:00
parent 91eec92b73
commit 6aa4427186
4 changed files with 1449 additions and 0 deletions
@@ -125,6 +125,12 @@ target_link_libraries(secs_conformance PRIVATE secsgem)
 add_executable(secs_bench apps/secs_bench.cpp)
 target_link_libraries(secs_bench PRIVATE secsgem)

+# Worked vendor example: ACME-PVD-3000.  Reads its own YAML, runs
+# sensor simulators + a recipe runner + alarm monitors + EPT cycling
+# + a Prometheus metrics exporter.  See examples/pvd_tool/README.md.
+add_executable(pvd_tool examples/pvd_tool/main.cpp)
+target_link_libraries(pvd_tool PRIVATE secsgem)
+
 if(SECSGEM_FUZZ)
  # libFuzzer entry-point targets.  Each owns its own `main` via the
  # `-fsanitize=fuzzer` link flag; do NOT also link them into the
@@ -0,0 +1,154 @@
+# ACME-PVD-3000 — worked vendor example
+
+A fictional Physical Vapor Deposition tool, end-to-end.  This is what
+a real tool integrator's deployment looks like:
+
+- `equipment.yaml` — the tool's data dictionary (32 SVIDs, 5 DVIDs,
+  7 ECIDs, 17 CEIDs, 12 alarms, 3 recipes, 9 host commands)
+- `main.cpp` — the vendor application: sensor simulator, recipe
+  runner, alarm threshold monitor, EPT cycling, metrics exporter,
+  Router handlers wiring it all to the wire.
+
+If you're starting a real integration, **fork these two files** and
+customize.  They're written to be a template, not an abstract demo.
+
+## What it demonstrates
+
+| Section in main.cpp           | What it shows you how to do                                          |
+|-------------------------------|----------------------------------------------------------------------|
+| §1 Helpers + constants        | The few `kSvidX / kCeidX` constants worth pinning at file scope      |
+| §2 Sensor simulator           | Multi-cadence sensor poll loops (10 Hz pressure, 1 Hz temps), with the `asio::post`-onto-strand thread-safety pattern |
+| §3 Recipe runner              | Driving a PJ through SettingUp → Processing → ProcessComplete by walking the recipe body, with per-step CEID emission |
+| §4 Alarm threshold monitor    | Continuous threshold-based alarm logic (chamber pressure, cleaning interval) with set/clear emission |
+| §5 EPT cycling                | E116 state transitions driven by PJ state + safety alarms             |
+| §6 Metrics                    | Prometheus exporter on `:9090` with per-CEID counters and gauge updates |
+| §7 Router handlers            | Every SECS/GEM message a host might send to a PVD tool, ~40 handlers in ~200 lines |
+| §8 main()                     | Loading YAML → validating → composing → running                       |
+
+## Running it
+
+From repo root:
+
+```bash
+# Validate the configs (this is what your CI should do).
+docker compose run --rm builder /app/build/secs_server --validate-config \
+    --config /app/examples/pvd_tool/equipment.yaml \
+    --state-table /app/data/control_state.yaml \
+    --pj-state-table /app/data/process_job_state.yaml \
+    --cj-state-table /app/data/control_job_state.yaml
+
+# Start the tool.
+docker compose run --rm builder /app/build/pvd_tool \
+    /app/examples/pvd_tool/equipment.yaml \
+    /app/data/control_state.yaml \
+    5000 \
+    9090
+
+# In another shell, drive it with the conformance harness or a real host.
+docker compose run --rm builder /app/build/secs_conformance \
+    --host 127.0.0.1 --port 5000 --device 0
+# 47 / 47 checks passed
+```
+
+Or via Docker Compose if you'd rather wire it as a service.
+
+## What the host sees
+
+Once a host connects and SELECTs:
+
+1. **S1F1 → S1F2** returns `MDLN="ACME-PVD-3000"`, `SOFTREV="1.4.2"`.
+2. **S1F3** on the 32 SVIDs returns live sensor readings — chamber
+   pressure tracks the simulator's target (default 1e-7 Torr in
+   idle), wafer counter increments per processed PJ, EPT state
+   gauge says `Standby`.
+3. **S2F33/F35/F37** binds dynamic event reports; CEIDs 300 / 301 /
+   310 / 311 fire on real PJ activity.
+4. **S2F41 RCMD=START** kicks the recipe runner: any PJ in
+   WaitingForStart transitions to Processing and the simulator
+   starts tracking the recipe's step targets.  Sensor values change
+   in real time.  CEID 300 (ProcessStarted) emits, then per-step
+   CEID 310/311, then CEID 301 (ProcessCompleted) on completion.
+5. **S2F41 RCMD=FAULT** sets alarm 4 → S5F1 emitted (if enabled
+   via S5F3 first).
+6. **S7F19** lists the 3 recipes; **S7F5** returns the body
+   (multi-line STEP definitions).
+7. **S16F11** (PJ create) + **S14F9** (CJ create) + **S16F27**
+   (CJSTART) drives the full E40/E94 lifecycle.
+
+## What's the same as the secs-gem demo server
+
+`apps/secs_server.cpp` (used by `docker compose up server`) is the
+canonical fully-loaded server.  This example is structurally a
+slimmer fork:
+
+- Same Router pattern (`gem::Router` + `router.on(s, f, [...])`)
+- Same event/alarm emission helpers (`deliver_or_spool`,
+  `emit_event`, `emit_alarm_set`)
+- Same control-state-change handler wiring
+
+What this example adds that the demo doesn't:
+
+- **Sensor simulator** with multi-cadence poll loops.  The demo's
+  SVID values stay at their YAML defaults; PVD's drift toward
+  recipe-step targets.
+- **Recipe runner** that parses the recipe body and drives the PJ
+  FSM step-by-step.  The demo's RCMD=START just emits the linked
+  CEID; PVD actually walks the recipe.
+- **Alarm threshold monitor** — continuous evaluation of sensor
+  values against ECID setpoints.  The demo only fires alarms when
+  RCMD=FAULT is sent.
+- **EPT cycling** — automatic Standby↔Productive↔UnscheduledDowntime
+  based on PJ + alarm state.  The demo doesn't cycle EPT.
+- **Prometheus metrics exporter** on a second port.  The demo logs
+  but doesn't export.
+
+If you want one of these patterns in your own tool, lift the code
+from `main.cpp` directly — each section is independently usable.
+
+## What's not here
+
+- **Persistence.** The demo server's `--spool-dir` flag is the
+  pattern to copy.  Add `model->spool.enable_persistence(...)` etc.
+  at startup before binding the port.  See INTEGRATION.md §5.
+- **E84 handshake timers.** No load-port AMHS wiring; see
+  INTEGRATION.md §4.6 for the `E84AsioTimers` adapter.
+- **Real I/O bridges.** Sensor values come from a random-walk
+  simulator.  A real PVD tool would have a PLC/serial driver
+  module-bridge feeding `model->svids.set_value(...)` from real
+  hardware.
+- **Production deployment hardening** — SECURITY.md (nftables,
+  stunnel, minisign signing) and INTEGRATION.md §7 (HA pattern).
+
+## What you'd change for *your* tool
+
+1. **Replace `equipment.yaml`** with your tool's actual SVIDs,
+   ECIDs, alarms, recipes.  Run
+   `secs_server --validate-config` after every edit.
+2. **Replace the sensor simulator** (`pvd::Simulator`) with calls
+   into your real hardware driver.  Keep the `asio::post` pattern
+   for cross-thread updates.
+3. **Replace the recipe runner** with your real recipe engine
+   integration.  The shape — fire `Start`, walk steps, fire
+   `ProcessComplete` — is the contract; the implementation is
+   yours.
+4. **Replace the alarm threshold monitor** with your real
+   alarm sources (sensor interrupts, watchdog timers, hardware
+   fault lines).  Same `emit_alarm_set / emit_alarm_clear` API.
+5. **Keep most of the Router handler section** — those are spec-
+   defined and you'll need them all in production.
+
+That's it.  No framework, no DI container, no abstract base
+classes.  ~700 lines of vendor code on top of the library.
+
+## Cross-references
+
+- [INTEGRATION.md](../../INTEGRATION.md) — the conceptual tutorial
+  this example concretizes
+- [ARCHITECTURE.md](../../ARCHITECTURE.md) — how stores compose, how
+  to extend
+- [BENCHMARKS.md](../../BENCHMARKS.md) — what the throughput
+  envelope looks like
+- [SECURITY.md](../../SECURITY.md) — production hardening configs
+- [apps/secs_server.cpp](../../apps/secs_server.cpp) — the demo
+  server's fully-loaded Router (every handler PVD inherits + a
+  few more)
@@ -0,0 +1,196 @@
+# ACME-PVD-3000 — example data dictionary for a fictional Physical
+# Vapor Deposition tool.  Designed to look like a real fab tool, not a
+# unit-test fixture.  Read this alongside main.cpp to see how each
+# entry is wired to behaviour.
+#
+# Topology:
+#   - One process chamber, single-wafer
+#   - Four load ports, each accepting a 25-slot FOUP
+#   - Three deposition recipes (Al / Ti / Cu)
+#
+# Real PVD tools have hundreds of SVIDs.  This one ships 30 — enough
+# to demonstrate every wiring pattern (status, derived, setpoint,
+# event, alarm, recipe, host command) without burying the example.
+
+device:
+  id: 0
+  model_name: "ACME-PVD-3000"
+  software_rev: "1.4.2"
+  equipment_type: "PVD"
+
+# E30 §6.10 — what the equipment self-reports to the host on S1F19.
+# CCODE values follow E30 Appendix A.
+capabilities:
+  - {code: 1,  name: "Establish Communications"}
+  - {code: 2,  name: "Dynamic Event Report Configuration"}
+  - {code: 3,  name: "Variable Data Collection"}
+  - {code: 5,  name: "Status Data Collection"}
+  - {code: 6,  name: "Alarm Management"}
+  - {code: 7,  name: "Remote Control"}
+  - {code: 8,  name: "Equipment Constants"}
+  - {code: 9,  name: "Process Program Management"}
+  - {code: 11, name: "Equipment Terminal Services"}
+  - {code: 12, name: "Clock"}
+  - {code: 14, name: "Spooling"}
+  - {code: 15, name: "Control (operator initiated)"}
+  - {code: 40, name: "E40 Process Job Management"}
+  - {code: 87, name: "E87 Carrier Management"}
+  - {code: 90, name: "E90 Substrate Tracking"}
+  - {code: 94, name: "E94 Control Job Management"}
+  - {code: 116, name: "E116 Equipment Performance Tracking"}
+  - {code: 148, name: "E148 Time Synchronization"}
+  - {code: 157, name: "E157 Module Process Tracking"}
+
+# Status variables — read-only, host queries via S1F3.
+# main.cpp updates the sensor values on a poll loop.
+svids:
+  # Mandatory framework SVIDs
+  - {id: 1, name: ControlState,    units: "",       type: ASCII, value: ""}
+  - {id: 2, name: Clock,           units: "",       type: ASCII, value: ""}
+  - {id: 3, name: EventsEnabled,   units: "",       type: BOOLEAN, value: true}
+  # Equipment-defined
+  - {id: 10, name: ProcessChamberPressureTorr, units: "Torr", type: F4, value: 1.0e-7}
+  - {id: 11, name: ProcessChamberTemperatureC, units: "C",    type: F4, value: 23.5}
+  - {id: 12, name: LoadlockPressureTorr,       units: "Torr", type: F4, value: 760.0}
+  - {id: 13, name: VacuumPumpRpm,              units: "rpm",  type: U4, value: 0}
+  - {id: 20, name: SourcePowerWatts,           units: "W",    type: F4, value: 0.0}
+  - {id: 21, name: TargetVoltageVolts,         units: "V",    type: F4, value: 0.0}
+  - {id: 22, name: SubstrateBiasVolts,         units: "V",    type: F4, value: 0.0}
+  - {id: 23, name: SourceTargetMaterial,       units: "",     type: ASCII, value: "None"}
+  - {id: 30, name: ArgonFlowSccm,              units: "sccm", type: F4, value: 0.0}
+  - {id: 31, name: NitrogenFlowSccm,           units: "sccm", type: F4, value: 0.0}
+  - {id: 32, name: CoolingWaterFlowLpm,        units: "L/min", type: F4, value: 12.5}
+  - {id: 40, name: ChuckTemperatureC,          units: "C",    type: F4, value: 24.0}
+  - {id: 41, name: ShieldTemperatureC,         units: "C",    type: F4, value: 24.0}
+  - {id: 50, name: WafersProcessedTotal,       units: "wafer", type: U4, value: 0}
+  - {id: 51, name: WafersProcessedSinceCleanup, units: "wafer", type: U4, value: 0}
+  - {id: 52, name: ChamberHoursSinceCleanup,   units: "h",    type: F4, value: 0.0}
+  - {id: 53, name: ActiveRecipePpid,           units: "",     type: ASCII, value: ""}
+  - {id: 54, name: RecipeStepName,             units: "",     type: ASCII, value: ""}
+  - {id: 55, name: RecipeStepElapsedSec,       units: "s",    type: U4, value: 0}
+  - {id: 60, name: LoadPort1Active,            units: "",     type: BOOLEAN, value: false}
+  - {id: 61, name: LoadPort2Active,            units: "",     type: BOOLEAN, value: false}
+  - {id: 62, name: LoadPort3Active,            units: "",     type: BOOLEAN, value: false}
+  - {id: 63, name: LoadPort4Active,            units: "",     type: BOOLEAN, value: false}
+  - {id: 70, name: EptStateName,               units: "",     type: ASCII, value: "Standby"}
+  - {id: 71, name: ProductiveHoursTotal,       units: "h",    type: F4, value: 0.0}
+  - {id: 72, name: UnscheduledDowntimeHours,   units: "h",    type: F4, value: 0.0}
+
+# Data variables — same shape as SVIDs but conceptually "intermediate
+# data" rather than equipment status.  Reported via S1F21/F22.
+dvids:
+  - {id: 200, name: LastCycleTimeSec,      units: "s",      type: F4, value: 0.0}
+  - {id: 201, name: AverageCycleTimeSec,   units: "s",      type: F4, value: 0.0}
+  - {id: 202, name: BatchYieldPercent,     units: "%",      type: F4, value: 0.0}
+  - {id: 203, name: LastWaferProcessedId,  units: "",       type: ASCII, value: ""}
+  - {id: 204, name: ProcessChamberLeakRate, units: "Torr/s", type: F4, value: 1.0e-9}
+
+# Equipment constants — host-settable parameters.  S2F15 set, S2F13 read.
+ecids:
+  - {id: 100, name: ChamberBasePressureSetpoint, units: "Torr", type: F4, value: 1.0e-7, min: "1.0e-9", max: "1.0e-5"}
+  - {id: 101, name: ChamberTempSetpointC,         units: "C",    type: F4, value: 25.0,   min: "15.0", max: "40.0"}
+  - {id: 102, name: SourcePowerSetpointW,         units: "W",    type: F4, value: 1500.0, min: "0.0",  max: "5000.0"}
+  - {id: 103, name: T_CRA_Seconds,                units: "s",    type: U4, value: 30,     min: "5",    max: "120"}
+  - {id: 104, name: T_DELAY_Seconds,              units: "s",    type: U4, value: 10,     min: "5",    max: "60"}
+  - {id: 105, name: CleaningIntervalWafers,       units: "wafer", type: U4, value: 500,   min: "100",  max: "2000"}
+  - {id: 106, name: MaxRecipeRetries,             units: "",     type: U4, value: 3,      min: "0",    max: "10"}
+
+# Collection events.  CEID → linked report binding happens at runtime
+# via S2F33/F35/F37; the equipment fires S6F11 on transitions through
+# main.cpp's event-emit hooks.
+ceids:
+  # Control / lifecycle
+  - {id: 100, name: ControlStateChanged}
+  - {id: 200, name: AlarmSet}
+  - {id: 201, name: AlarmCleared}
+  # Process lifecycle
+  - {id: 300, name: ProcessStarted}
+  - {id: 301, name: ProcessCompleted}
+  - {id: 302, name: ProcessAborted}
+  - {id: 303, name: ProcessPaused}
+  - {id: 304, name: ProcessResumed}
+  - {id: 310, name: RecipeStepStarted}
+  - {id: 311, name: RecipeStepCompleted}
+  # Material movement
+  - {id: 400, name: ControlJobExecuting}
+  - {id: 401, name: ControlJobCompleted}
+  - {id: 410, name: CarrierLoaded}
+  - {id: 411, name: CarrierUnloaded}
+  - {id: 420, name: SubstrateAtSource}
+  - {id: 421, name: SubstrateInProcess}
+  - {id: 422, name: SubstrateProcessed}
+  # Equipment performance (E116)
+  - {id: 500, name: EptEnteredProductive}
+  - {id: 501, name: EptEnteredStandby}
+  - {id: 502, name: EptEnteredEngineering}
+  - {id: 503, name: EptEnteredUnscheduledDowntime}
+
+# Alarms.  Categories follow E5 §10.3 ALCD lower-7 bitmap:
+#   0x01 PersonalSafety   0x02 EquipmentSafety   0x04 ParameterError
+#   0x08 ParameterWarning 0x10 Irrecoverable     0x20 EquipmentStatus
+#   0x40 Attention
+alarms:
+  - {id: 1,  text: "Chamber pressure high (above setpoint)",       category: 0x04}
+  - {id: 2,  text: "Chamber pressure low (below setpoint)",         category: 0x04}
+  - {id: 3,  text: "Chamber temperature out of range",              category: 0x04}
+  - {id: 4,  text: "Source power loss during process",              category: 0x12}  # safety + error
+  - {id: 5,  text: "Cooling water flow loss",                       category: 0x02}  # equip safety
+  - {id: 6,  text: "Vacuum pump failure",                           category: 0x12}
+  - {id: 7,  text: "Door open during process",                       category: 0x01}  # personal safety
+  - {id: 8,  text: "Target end-of-life",                            category: 0x40}  # attention
+  - {id: 9,  text: "Recipe step timeout",                            category: 0x08}  # warning
+  - {id: 10, text: "Cleaning interval exceeded (500 wafers)",       category: 0x40}
+  - {id: 11, text: "Load port 1 carrier mis-clocked",                category: 0x20}
+  - {id: 12, text: "Substrate scanner unavailable",                  category: 0x20}
+
+# Recipes.  The body is a placeholder string in this example; real
+# tools would store binary recipe bundles (E42 formatted PP) here.
+# The recipe runner in main.cpp parses the body line-by-line.
+recipes:
+  - id: "AL-METALLIZATION-V3"
+    body: |
+      STEP PUMPDOWN          duration=120s    target=1.0e-7
+      STEP HEAT-SUBSTRATE    duration=60s     target=300C
+      STEP SOURCE-PREHEAT    duration=30s     power=500W
+      STEP DEPOSIT-AL        duration=180s    power=2500W gas=Argon flow=50sccm
+      STEP COOL              duration=120s    target=25C
+      STEP VENT              duration=60s     target=760
+      END
+  - id: "TI-BARRIER-V2"
+    body: |
+      STEP PUMPDOWN          duration=120s    target=1.0e-7
+      STEP HEAT-SUBSTRATE    duration=60s     target=350C
+      STEP DEPOSIT-TI        duration=90s     power=1800W gas=Argon flow=40sccm
+      STEP COOL              duration=120s    target=25C
+      STEP VENT              duration=60s     target=760
+      END
+  - id: "CU-SEED-V1"
+    body: |
+      STEP PUMPDOWN          duration=120s    target=1.0e-7
+      STEP HEAT-SUBSTRATE    duration=60s     target=250C
+      STEP DEPOSIT-CU        duration=240s    power=3000W gas=Argon flow=60sccm
+      STEP COOL              duration=120s    target=25C
+      STEP VENT              duration=60s     target=760
+      END
+
+# Host commands.  `emit_ceid` fires the named CEID after dispatch;
+# `set_alarm` sets an alarm.  `force_spool` is the demo-only test hook.
+host_commands:
+  - {name: START,         ack: Accept, emit_ceid: 300}
+  - {name: STOP,          ack: Accept, emit_ceid: 301}
+  - {name: PAUSE,         ack: Accept, emit_ceid: 303}
+  - {name: RESUME,        ack: Accept, emit_ceid: 304}
+  - {name: ABORT,         ack: Accept, emit_ceid: 302}
+  - {name: CLEAN_CHAMBER, ack: Accept}
+  - {name: FAULT,         ack: Accept, set_alarm: 4}     # injected fault for demo
+  - {name: SPOOL_ON,      ack: Accept, force_spool: true}
+  - {name: SPOOL_OFF,     ack: Accept, force_spool: false}
+
+# Spool (E30 §6.22) — when the host disconnects, queue these streams
+# for later drain via S6F23.
+spool:
+  max_size: 1000
+  spoolable_streams: [5, 6]
+
+# Auto-fire CEID 100 on every control-state change.
+emit_on_control_change: 100