raphael
195ecc689f
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>
14 KiB
14 KiB
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. |
| 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 — when you've grasped the vocabulary, this is how you put it together.
- COMPLIANCE.md — every term above has a spec-anchored implementation; the audit cross-references both.
- FAQ.md — "OK, but why…" answers for the most common next questions.