raphael/secs-gem
Public Access
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: GLOSSARY + FAQ + interop README refresh + doc-map fixes

Browse Source 
Fills four documentation gaps surfaced by the doc audit:

1. README "Documentation map" was missing VERIFICATION.md (the file
   that backs the proof-of-feature-completeness claims) and is now
   pointing at the new files added in this commit too — ARCHITECTURE,
   GLOSSARY, FAQ, examples/pvd_tool/ (the last two land next).

2. interop/README.md only documented secsgem-py.  Three of the five
   external validators (tshark, secs4j, libFuzzer) plus the E5 KAT
   were invisible from the directory's own README.  Rewritten as a
   complete index — what's external, what each catches, how to run,
   what bugs they've already surfaced, when to add a new validator.

3. GLOSSARY.md is new.  Every SEMI acronym used in the codebase or
   the docs gets one row: SVID, DVID, CEID, RPTID, ALID, ECID, PPID,
   MID, CARRIERID, PRJOBID, CTLJOBID, SUBSTID, OBJSPEC, OBJTYPE,
   MDLN, SOFTREV, EQPTYP, DATAID + every ACK code (COMMACK, ONLACK,
   OFLACK, HCACK, CMDA, ACKC5-7-10, DRACK, LRACK, ERACK, EAC, TIACK,
   GRANT, ALCD, OBJACK) + stream/function shorthand + HSMS terms +
   T-timers + E84 signals + the standards lineup + codebase shortcuts
   ("the model", "the router", "the proof", etc.).  Cuts week-1
   onboarding time.

4. FAQ.md is new.  Canonical answers to the questions that come up
   once per integration: why HSMS unencrypted, SVID vs DVID, PJ vs
   CJ, who fires FSM transitions, what runs on which thread, how to
   add a new SECS-II message, ASCII vs Binary, common MES quirks,
   how spool works, robustness fuzz vs libFuzzer, conformance vs
   interop, what's not implemented.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Raphael Maenle
2026-06-09 16:43:45 +02:00
parent db90a21e1d
commit 195ecc689f
4 changed files with 506 additions and 39 deletions
Download Patch File Download Diff File Expand all files Collapse all files
GLOSSARY.md
+163
View File
@@ -0,0 +1,163 @@
# Glossary
SECS/GEM has roughly thirty acronyms that the spec uses without
introduction. This is the one-page decoder. Each entry has the
expansion, a one-line definition, and (where useful) the place in
this codebase where it shows up.
## Identifiers and data
| Term | Stands for | Meaning |
|------------|----------------------------------|------------------------------------------------------------------------------------------|
| **SVID** | Status Variable Identifier | A read-only equipment-side value the host queries via `S1F3` (e.g. ChamberPressureTorr). |
| **DVID** | Data Variable Identifier | Same shape as SVID but conceptually a *data variable* (intermediate, not status). Reported via `S1F21/F22`. |
| **ECID** | Equipment Constant Identifier | A host-settable equipment parameter (e.g. T-timers, thresholds). Set via `S2F15`, read via `S2F13`. |
| **CEID** | Collection Event Identifier | An event the equipment can emit (e.g. `ProcessStarted`). Bound to reports via `S2F35`, fires via `S6F11`. |
| **RPTID** | Report Identifier | A named bundle of VIDs (`S2F33`). CEIDs link to RPTIDs; the report carries the VID values. |
| **ALID** | Alarm Identifier | An equipment alarm (e.g. `ChamberPressureHigh`). `S5F5/F1/F3`. |
| **EXID** | Exception Identifier | A recoverable exception condition. `S5F9 → S5F13 → S5F11/F15` lifecycle. |
| **PPID** | Process Program Identifier | A recipe name. `S7F19` lists, `S7F5` requests, `S7F3` sends. |
| **MID** | Material Identifier | A wafer / substrate id (used in E40 PJ `mtrloutspec`). |
| **CARRIERID** | Carrier Identifier | A FOUP / cassette id (E87). |
| **PRJOBID**| Process Job Identifier | E40 PJ id; one PJ = one recipe-run for one batch of material. |
| **CTLJOBID** | Control Job Identifier | E94 CJ id; a CJ owns an ordered list of PRJOBIDs. |
| **SUBSTID**| Substrate Identifier | E90 wafer id, distinct from MID (which can be looser). |
| **OBJSPEC** | Object Specifier | E39 generic object reference (e.g. an instance of an E120 CEM object). |
| **OBJTYPE** | Object Type | Companion to OBJSPEC — the class. |
| **MDLN** | Model Number | Equipment model identifier (e.g. `ACME-PVD-3000`). Sent in `S1F2` and `S1F14`. |
| **SOFTREV**| Software Revision | Equipment software version string. Sent in `S1F2` and `S1F14`. |
| **EQPTYP** | Equipment Type | A category string (e.g. `PVD`) sent in `S1F20`. |
| **DATAID** | Data Identifier | A correlation id within multi-step setups (e.g. tying `S2F33`+`S2F35`+`S2F37` together). |
## Acknowledgement codes
Every host-issued request that mutates state gets back a 1-byte
acknowledgement code. The mnemonic tells you which spec section
the enum lives in.
| Code | Used in | Values |
|-----------|-------------------|---------------------------------------------------------------------------------------------|
| **COMMACK**| `S1F14` | 0 = Accept, 1 = Denied (equipment not ready). |
| **ONLACK** | `S1F18` | 0 = Accept, 1 = NotAccept, 2 = AlreadyOnline. |
| **OFLACK** | `S1F16` | Only 0 = Accept defined. |
| **HCACK** | `S2F42` / `S16F6` / `S16F12` etc. | 0 = Accept, 1 = InvalidCommand, 2 = CannotDoNow, 3 = ParameterInvalid, 4 = AcceptedWillFinishLater, 5 = Rejected, 6 = InvalidObject. |
| **CMDA** | `S2F22` | Same enum as HCACK; spelled differently in the spec. |
| **ACKC5** | `S5F4` / `S5F2` | 0 = Accept, 1 = Error. |
| **ACKC6** | `S6F12` / `S6F2` etc. | 0 = Accept, 1 = Error. |
| **ACKC7** | `S7F4` / `S7F18` | 0 = Accept, 1-6 = various PP-management errors. |
| **ACKC10** | `S10F2` / `S10F4` / `S10F6` | 0 = Accept, 1-3 = TerminalDisplay errors. |
| **DRACK** | `S2F34` | Define Report Ack: 0 = Accept, 1-4 = various definition errors. |
| **LRACK** | `S2F36` | Link Event Ack: 0 = Accept, 1-5. |
| **ERACK** | `S2F38` | Enable Event Ack: 0 = Accept, 1 = UnknownCEID. |
| **EAC** | `S2F16` | Equipment Constant ack: 0 = Accept, 1 = Denied_OutOfRange, 2 = BusyOrUnknown, 3 = MajorOOR.|
| **TIACK** | `S2F32` | Time Ack: 0 = Accept, 1 = Error, 2 = NotDone. |
| **GRANT** | `S2F40` / `S6F6` | 0 = Grant, 1-3 = denials. |
| **ALCD** | `S5F1` | **Alarm Code**: bit-7 = set/clear flag; lower 7 bits = severity bitmap (E5 §10.3). |
| **OBJACK** | `S14F2` / `S14F10` etc. | E39 object service ack: 0 = Success, plus per-call denial codes. |
## Streams and functions
SECS-II messages are named **`SsFf`** — Stream *s*, Function *f*.
Odd functions are **primary** (initiating a transaction); even
functions are the **reply** to function *f − 1*. A primary with the
**W-bit** set expects a reply.
| Stream | Domain | Example exchange |
|-------:|----------------------------------------------|------------------------------------------------------------------|
| S1 | Equipment status | S1F1/F2 "Are You There", S1F13/F14 Establish Comms |
| S2 | Equipment control + configuration | S2F33 define report, S2F41 host command |
| S3 | E87 carrier management | S3F17 CarrierAction, S3F19 SlotMapVerify |
| S5 | Exception reporting | S5F1 alarm send, S5F9-F18 exception recovery |
| S6 | Data collection | S6F11 unsolicited event report, S6F15 event report request |
| S7 | Process program management | S7F5 PP request, S7F19 PP list, S7F23 E42 formatted PP |
| S9 | System errors | S9F1, F3, F5, F7, F9, F11 — protocol-error notifications |
| S10 | Terminal services | S10F3 host→equipment display, S10F1 equipment→host |
| S12 | Wafer maps (E5 §13) | S12F1 setup, S12F7/F9/F11 send (3 formats) |
| S14 | E39 / E94 object services | S14F1 GetAttr, S14F9 CreateControlJob |
| S16 | E40 / E94 jobs | S16F11 PRJobCreate, S16F27 CJobCommand |
## HSMS terminology
| Term | Stands for | Meaning |
|------------|----------------------------------|------------------------------------------------------------------------------------------|
| **HSMS** | High-Speed Message Service | The TCP-based SECS transport defined by SEMI E37. |
| **HSMS-SS**| Single-Session | The common case: one session per TCP connection. |
| **HSMS-GS**| General-Session | Multi-session: multiple session IDs share one TCP connection. |
| **PType** | Presentation Type | 1-byte header field; 0 = SECS-II body. |
| **SType** | Session Type | 1-byte header field identifying the message class (data, Select.req, Linktest, etc.). |
| **MHEAD** | Message Header (10 bytes) | The HSMS framing header; appears unchanged in `S9F3/F5/F7/F11` payloads. |
| **NOT-SELECTED** / **SELECTED** | HSMS connection state | Reached via Select.req/rsp; required before data messages can flow. |
## T-timers (E37 §10)
| Timer | Purpose | Typical default | Where enforced |
|------:|----------------------------------------------------|-----------------|----------------------|
| **T3**| Reply timeout for a W=1 primary | 45 s | per-transaction asio timer |
| **T5**| Connect-separation: how long before retrying after a connection failure | 10 s | client retry loop |
| **T6**| Control transaction timeout (Select / Linktest) | 5 s | one concurrent control transaction |
| **T7**| Not-selected timeout — passive side, after TCP up | 10 s | armed on accept |
| **T8**| Intercharacter timeout — bounds the payload read after the 4-byte length prefix | 6 s | data-read loop |
For SECS-I (E4), T1/T2/T3/T4 are the analogous serial-line timers
covering inter-character, protocol, reply, and inter-block respectively.
## E84 signals (parallel I/O, AMHS handshake)
| Signal | Direction | Meaning |
|--------|-------------------------|-----------------------------------------------|
| CS_0 | AMHS → equipment | Carrier-stage select 0 (multi-port equipment) |
| CS_1 | AMHS → equipment | Carrier-stage select 1 |
| VALID | AMHS → equipment | Handshake start |
| TR_REQ | AMHS → equipment | Transfer request |
| BUSY | AMHS → equipment | Transfer in progress |
| COMPT | AMHS → equipment | Transfer complete |
| L_REQ | equipment → AMHS | Load request — port ready to receive |
| U_REQ | equipment → AMHS | Unload request — port ready to release |
| READY | equipment → AMHS | Ready |
| ES | either | Emergency stop |
Handshake timers TA1 (VALID→L_REQ), TA2 (Load/UnloadReady→BUSY),
TA3 (BUSY duration) live alongside the signals — see
`include/secsgem/gem/e84_state.hpp` and INTEGRATION.md §4.6.
## Standards lineup
| Spec | Topic |
|---------|-------------------------------------------------|
| **E4** | SECS-I serial transport (block protocol) |
| **E5** | SECS-II message structure + encoding rules |
| **E30** | GEM — generic equipment model + capabilities |
| **E37** | HSMS — TCP transport for SECS-II |
| **E39** | Generic object services (`S14F1/F3` GetAttr/SetAttr) |
| **E40** | Process job management (`S16F5/F11/F13`) |
| **E42** | Formatted process programs (`S7F23-F26`) |
| **E84** | Parallel I/O AMHS handshake |
| **E87** | Carrier management (`S3F17/F19/F25/F27`) |
| **E90** | Substrate tracking |
| **E94** | Control job management (`S14F9/F11`, `S16F27`) |
| **E116**| Equipment Performance Tracking |
| **E120**| Common Equipment Model |
| **E148**| Time synchronization |
| **E157**| Module process tracking |
## Codebase shortcuts
| Term | What it refers to in this repo |
|-----------------|-----------------------------------------------------------------------|
| **The model** | `gem::EquipmentDataModel` — the composed bundle of every store. |
| **A store** | One of the per-domain bundles under `include/secsgem/gem/store/` (alarms, carriers, spool, substrates, …). |
| **The router** | `gem::Router` — `(stream, function) → handler` dispatch table. |
| **The codec** | `secs2::encode` / `secs2::decode` for the wire bytes. |
| **The catalog** | `data/messages.yaml` — every SECS-II message we ship, codegen'd to `messages.hpp`. |
| **The proof** | The 8 commands in [README.md](README.md#proof-of-feature-completeness). |
| **The bench** | `apps/secs_bench.cpp` — single-threaded throughput / latency / memory harness. |
| **The fuzz** | `tests/test_robustness_fuzz.cpp` — randomized property test of the model. |
## See also
- [INTEGRATION.md](INTEGRATION.md) — when you've grasped the
vocabulary, this is how you put it together.
- [COMPLIANCE.md](COMPLIANCE.md) — every term above has a
spec-anchored implementation; the audit cross-references both.
- [FAQ.md](FAQ.md) — "OK, but *why*…" answers for the most common
next questions.