Public Access

Files

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

14 KiB

Raw Blame History

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.
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.

14 KiB Raw Blame History Unescape Escape