raphael/secs-gem
Public Access
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b031f057afeccd306626926cc8f9c86aa9f2d7d6
secs-gem/GLOSSARY.md
T
raphael b031f057af docs: customer-ready sweep + README restructure + tshark CI fix 
Audit pass over the public-facing surface so a customer can read it
end-to-end without tripping on stale numbers or self-contradictions.

README + docs accuracy:
- Test counts 426 → 445, assertions 2 557 → 2 753 (verified via
  doctest run); E5 row was missing test_e5_kat (19 cases)
- Interop checks 24 → 31, COMPLIANCE.md message count 149 → 164,
  COMPLIANCE.md "291 cases / 1515 assertions" → 445 / 2 753
- README "60+ test IDs" for MES_INTEROP → actual 59
- PVD example counts: 32 SVIDs/17 CEIDs → 29/21, "~40 handlers
  in ~200 lines" → 51 in ~460, "~700 lines" → ~1,100; main.cpp
  header table-of-contents resynced with the actual 7 sections

Out-of-scope honesty (COMPLIANCE.md §8 + FAQ.md):
- Removed HSMS-GS (was both ✅ implemented in §1 and "out of scope"
  in §8; INTEGRATION.md §7 documents using it)
- Removed multi-block SECS-I (split_message/assemble_message exist
  with 4 dedicated tests)
- Added serial-port wiring as the genuine open ⬜ item — FSM is
  tested end-to-end over TCP; only the asio serial_port glue is
  deferred
- COMPLIANCE.md intro now lists E42 and notes "E37 (SS + GS)"

README restructure:
- Moved the 8-command proof table and per-standard test-coverage
  table to a new PROOFS.md (72 lines)
- README now leads with what / Quick start / Documentation map,
  then a one-paragraph "How it's proved" linking to PROOFS.md
- Updated cross-refs in FAQ.md, GLOSSARY.md, VERIFICATION.md, and
  interop/README.md to point at PROOFS.md

CI fix — tshark-dissector job:
- interop/tshark_validate.sh hardcoded /app/build/secs_server etc.
  which only works inside the docker image.  Now derives ROOT from
  the script's own location and accepts BUILD/SERVER/CLIENT/DATA
  env overrides, so CI can run it from the workspace dir
- Verified still passes in docker (69 frames, 0 malformed)

.gitignore:
- Added build-fuzz/ and build-tsan/ (were showing as untracked)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-09 18:59:17 +02:00

164 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 [PROOFS.md](PROOFS.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](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.
Reference in New Issue View Git Blame Copy Permalink