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

#6 SxFy codegen from YAML message catalog

Browse Source 
The bulk of the per-SxFy boilerplate — ~90 hand-written builders and parsers
across 30+ message pairs — is now generated at build time from a single YAML
catalog. Adding a new SECS-II message becomes a YAML edit; the C++ code is
generated, not maintained.

What changed
------------

data/messages.yaml
  The catalog. Describes every SxFy currently supported: stream, function,
  W-bit, builder name, optional parser name, and a recursive body shape
  grammar (scalar / list / list_of).  Shapes carry SECS-II item types
  (ASCII, BINARY_BYTE, U4, F8, ITEM, ...) and optional C++ enum types for
  typed ack codes.  Inner-most fields can be marked external_struct: true
  so structs already defined elsewhere (ReportData, CommandParameter) are
  referenced rather than redefined.

tools/gen_messages.py
  Python codegen.  Reads the catalog and emits one inline header.  Handles
  nested shapes via depth-unique variable names in the generated IIFEs, so
  S6F11's three-level nesting compiles without lambda capture conflicts.
  Post-order traversal ensures inner structs are emitted before outer ones
  that reference them.  Generates positional and (where applicable) struct
  builder overloads, plus struct-returning parsers for messages with a
  `parser:` entry.

CMakeLists.txt
  Custom command runs gen_messages.py at configure/build time and emits
  ${CMAKE_BINARY_DIR}/generated/secsgem/gem/messages.hpp.  Added to the
  secsgem target's include path so `#include "secsgem/gem/messages.hpp"`
  resolves to the generated file.  Depends on the YAML + the script, so
  edits trigger regen automatically.

Dockerfile
  Added python3 + python3-yaml to the toolchain image.

include/secsgem/gem/messages_helpers.hpp  (new)
  The small set of hand-written helpers the generated header relies on:
  scalar accessors (as_ascii / as_u4_scalar / ...), parse_u4_list_body,
  u4_list_item, ack_byte, ALED byte constants, and the two special-case
  messages whose shape doesn't fit the codegen schema (S1F4 needs
  per-row std::optional<Item> semantics; S5F6 needs a per-row ALCD
  callback).

include/secsgem/gem/messages.hpp  (deleted)
  The hand-written builder/parser file is gone. Its content now flows
  through the catalog + codegen.

include/secsgem/gem/data_model.hpp
  Moved CommandParameter to namespace scope so it can be shared between
  the data model and the messages.yaml's external_struct entry.  Added
  `using CommandParam = CommandParameter` for back-compat.

apps/secs_server.cpp + apps/secs_client.cpp
  Updated the call sites that the codegen renamed or restructured:
  - parse_terminal_display() split into parse_s10f1 / parse_s10f3.
  - s1f14_establish_comms_ack now takes a McAck struct for the nested
    identity (mdln, softrev) — call site uses brace init.
  - S2F33/S2F35 parsers return strongly-typed entries (DefineReportEntry,
    LinkEventEntry); the server adapts these to the model's pair-based
    API at the call site.
  - S2F15 parser returns vector<EcSet>; iterate by .ecid/.value.
  - S5F3 parser returns EnableAlarmRequest{aled, alid}; bool comes from
    (aled & 0x80) != 0.
  - AlarmReport's is_set()/category() methods removed; callers use the
    raw alcd byte with bit math (alcd & 0x80, alcd & 0x7F).
  - s2f42_host_command_ack and s2f41_host_command always take their
    second list argument explicitly (no defaulted arg from codegen).

tests/test_messages.cpp
  Updated to construct the generated typed structs (EcSet, StatusName,
  EnableAlarmRequest, CommandParameter, CommandParameterAck) and to read
  the new field names (.ecid/.value, .rptid/.vids, .ceid/.rptids,
  .name/.code).

Coverage
--------

Generated by codegen (44 SxFy in catalog):

  S1F1, S1F2, S1F3, S1F11, S1F12, S1F13, S1F14, S1F15, S1F16, S1F17, S1F18
  S2F13, S2F14, S2F15, S2F16, S2F17, S2F18, S2F29, S2F30, S2F31, S2F32
  S2F33, S2F34, S2F35, S2F36, S2F37, S2F38, S2F41, S2F42
  S5F1, S5F2, S5F3, S5F4, S5F5
  S6F11, S6F12
  S7F3, S7F4, S7F5, S7F6, S7F19, S7F20
  S10F1, S10F2, S10F3, S10F4

Hand-written (in messages_helpers.hpp):

  S1F4   list-of-optional-items shape (nullopt -> <L,0>)
  S5F6   per-row ALCD via callback

Adding a new SxFy
-----------------

Append a single entry to data/messages.yaml describing the body shape.
The builder + parser appear in messages.hpp after the next build.  The
host command above for S2F41 (or any other added SxFy) requires no C++
changes if the body fits the recursive scalar/list/list_of grammar.

Tests: 67 cases / 384 assertions still passing.
Demo: byte-for-byte identical behaviour (Select, Establish, Online,
S1F11/F3 namelist+values, S2F29 EC namelist, S2F33/F35/F37 dynamic event
subscription, S2F41 START -> S6F11 emission, S5F5/F3 alarm directory +
enable, S2F41 FAULT -> S5F1 alarm + S6F11, S7F19/F5 recipe ops, S10F1
terminal, S1F15 offline, Separate).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Raphael Maenle
2026-06-02 09:43:36 +02:00
parent b871cd9da2
commit 29db1caedb
10 changed files with 1151 additions and 810 deletions
Download Patch File Download Diff File Expand all files Collapse all files
data/messages.yaml
+546
View File
@@ -0,0 +1,546 @@
# SECS-II message catalog. Each entry describes one SxFy primary or reply;
# the codegen (tools/gen_messages.py) reads this and emits builders + parsers.
#
# Shape grammar (see tools/gen_messages.py for the full description):
#
# none - header-only (no body)
# scalar: - single Item; cpp_type derived from item_type/enum
# item_type: ASCII | BINARY_BYTE | BOOLEAN | U1..U8 | I1..I8 | F4 | F8 | ITEM
# enum: <C++ enum> - optional
# param: <name> - optional, default "value"
# list: - fixed-arity <L,k>
# fields: [{name, shape}, ...]
# struct_name: <Name> - optional; if set, parser returns the struct
# external_struct: bool - optional; struct is assumed to exist already
# list_of: - variable-arity <L,n>
# element: <shape>
# name: <param-name> - optional, default "values"
#
# Special-case messages whose shape can't be expressed (S1F4's optional-item
# semantics, S5F6's per-row ALCD callback) live in messages_helpers.hpp.
messages:
# =====================================================================
# S1 — Equipment status
# =====================================================================
- id: S1F1
stream: 1
function: 1
w: true
builder: s1f1_are_you_there
- id: S1F2
stream: 1
function: 2
builder: s1f2_on_line_data
body:
kind: list
fields:
- {name: mdln, shape: {kind: scalar, item_type: ASCII}}
- {name: softrev, shape: {kind: scalar, item_type: ASCII}}
- id: S1F3
stream: 1
function: 3
w: true
builder: s1f3_selected_status_request
parser: parse_s1f3
body:
kind: list_of
element: {kind: scalar, item_type: U4}
name: svids
- id: S1F11
stream: 1
function: 11
w: true
builder: s1f11_status_namelist_request
parser: parse_s1f11
body:
kind: list_of
element: {kind: scalar, item_type: U4}
name: svids
- id: S1F12
stream: 1
function: 12
builder: s1f12_status_namelist_data
parser: parse_s1f12
body:
kind: list_of
name: items
element:
kind: list
struct_name: StatusName
fields:
- {name: id, shape: {kind: scalar, item_type: U4}}
- {name: name, shape: {kind: scalar, item_type: ASCII}}
- {name: units, shape: {kind: scalar, item_type: ASCII}}
- id: S1F13
stream: 1
function: 13
w: true
builder: s1f13_establish_comms
body:
kind: list
fields:
- {name: mdln, shape: {kind: scalar, item_type: ASCII}}
- {name: softrev, shape: {kind: scalar, item_type: ASCII}}
- id: S1F14
stream: 1
function: 14
builder: s1f14_establish_comms_ack
body:
kind: list
fields:
- {name: ack, shape: {kind: scalar, item_type: BINARY_BYTE, enum: CommAck}}
- name: identity
shape:
kind: list
struct_name: McAck
fields:
- {name: mdln, shape: {kind: scalar, item_type: ASCII}}
- {name: softrev, shape: {kind: scalar, item_type: ASCII}}
- id: S1F15
stream: 1
function: 15
w: true
builder: s1f15_request_offline
- id: S1F16
stream: 1
function: 16
builder: s1f16_offline_ack
body: {kind: scalar, item_type: BINARY_BYTE, enum: OfflineAck, param: ack}
- id: S1F17
stream: 1
function: 17
w: true
builder: s1f17_request_online
- id: S1F18
stream: 1
function: 18
builder: s1f18_online_ack
body: {kind: scalar, item_type: BINARY_BYTE, enum: OnlineAck, param: ack}
# =====================================================================
# S2 — Equipment control + reports
# =====================================================================
- id: S2F13
stream: 2
function: 13
w: true
builder: s2f13_ec_request
parser: parse_s2f13
body:
kind: list_of
element: {kind: scalar, item_type: U4}
name: ecids
- id: S2F14
stream: 2
function: 14
builder: s2f14_ec_data
parser: parse_s2f14
body:
kind: list_of
element: {kind: scalar, item_type: ITEM}
name: values
- id: S2F15
stream: 2
function: 15
w: true
builder: s2f15_ec_send
parser: parse_s2f15
body:
kind: list_of
name: sets
element:
kind: list
struct_name: EcSet
fields:
- {name: ecid, shape: {kind: scalar, item_type: U4}}
- {name: value, shape: {kind: scalar, item_type: ITEM}}
- id: S2F16
stream: 2
function: 16
builder: s2f16_ec_ack
body: {kind: scalar, item_type: BINARY_BYTE, enum: EquipmentAck, param: eac}
- id: S2F17
stream: 2
function: 17
w: true
builder: s2f17_date_time_request
- id: S2F18
stream: 2
function: 18
builder: s2f18_date_time_data
parser: parse_s2f18
body: {kind: scalar, item_type: ASCII, param: time_str}
- id: S2F29
stream: 2
function: 29
w: true
builder: s2f29_ec_namelist_request
body:
kind: list_of
element: {kind: scalar, item_type: U4}
name: ecids
- id: S2F30
stream: 2
function: 30
builder: s2f30_ec_namelist_data
body:
kind: list_of
name: items
element:
kind: list
struct_name: EcNameRow
fields:
- {name: ecid, shape: {kind: scalar, item_type: U4}}
- {name: name, shape: {kind: scalar, item_type: ASCII}}
- {name: min_str, shape: {kind: scalar, item_type: ASCII}}
- {name: max_str, shape: {kind: scalar, item_type: ASCII}}
- {name: default_str, shape: {kind: scalar, item_type: ASCII}}
- {name: units, shape: {kind: scalar, item_type: ASCII}}
- id: S2F31
stream: 2
function: 31
w: true
builder: s2f31_date_time_set
parser: parse_s2f31
body: {kind: scalar, item_type: ASCII, param: time_str}
- id: S2F32
stream: 2
function: 32
builder: s2f32_date_time_ack
body: {kind: scalar, item_type: BINARY_BYTE, enum: TimeAck, param: ack}
- id: S2F33
stream: 2
function: 33
w: true
builder: s2f33_define_report
parser: parse_s2f33
body:
kind: list
struct_name: DefineReportRequest
fields:
- {name: dataid, shape: {kind: scalar, item_type: U4}}
- name: reports
shape:
kind: list_of
element:
kind: list
struct_name: DefineReportEntry
fields:
- {name: rptid, shape: {kind: scalar, item_type: U4}}
- name: vids
shape:
kind: list_of
element: {kind: scalar, item_type: U4}
- id: S2F34
stream: 2
function: 34
builder: s2f34_define_report_ack
body: {kind: scalar, item_type: BINARY_BYTE, enum: DefineReportAck, param: ack}
- id: S2F35
stream: 2
function: 35
w: true
builder: s2f35_link_event_report
parser: parse_s2f35
body:
kind: list
struct_name: LinkEventReportRequest
fields:
- {name: dataid, shape: {kind: scalar, item_type: U4}}
- name: links
shape:
kind: list_of
element:
kind: list
struct_name: LinkEventEntry
fields:
- {name: ceid, shape: {kind: scalar, item_type: U4}}
- name: rptids
shape:
kind: list_of
element: {kind: scalar, item_type: U4}
- id: S2F36
stream: 2
function: 36
builder: s2f36_link_event_report_ack
body: {kind: scalar, item_type: BINARY_BYTE, enum: LinkEventAck, param: ack}
- id: S2F37
stream: 2
function: 37
w: true
builder: s2f37_enable_event
parser: parse_s2f37
body:
kind: list
struct_name: EnableEventRequest
fields:
- {name: enable, shape: {kind: scalar, item_type: BOOLEAN}}
- name: ceids
shape: {kind: list_of, element: {kind: scalar, item_type: U4}}
- id: S2F38
stream: 2
function: 38
builder: s2f38_enable_event_ack
body: {kind: scalar, item_type: BINARY_BYTE, enum: EnableEventAck, param: ack}
- id: S2F41
stream: 2
function: 41
w: true
builder: s2f41_host_command
parser: parse_s2f41
body:
kind: list
struct_name: HostCommand
fields:
- {name: rcmd, shape: {kind: scalar, item_type: ASCII}}
- name: params
shape:
kind: list_of
element:
kind: list
struct_name: CommandParameter
external_struct: true
fields:
- {name: name, shape: {kind: scalar, item_type: ASCII}}
- {name: value, shape: {kind: scalar, item_type: ITEM}}
- id: S2F42
stream: 2
function: 42
builder: s2f42_host_command_ack
parser: parse_s2f42
body:
kind: list
struct_name: HostCommandReply
fields:
- {name: hcack, shape: {kind: scalar, item_type: BINARY_BYTE, enum: HostCmdAck}}
- name: cpacks
shape:
kind: list_of
element:
kind: list
struct_name: CommandParameterAck
fields:
- {name: name, shape: {kind: scalar, item_type: ASCII}}
- {name: code, shape: {kind: scalar, item_type: BINARY_BYTE}}
# =====================================================================
# S5 — Alarms
# =====================================================================
- id: S5F1
stream: 5
function: 1
w: true
builder: s5f1_alarm_report
parser: parse_s5f1
body:
kind: list
struct_name: AlarmReport
fields:
- {name: alcd, shape: {kind: scalar, item_type: BINARY_BYTE}}
- {name: alid, shape: {kind: scalar, item_type: U4}}
- {name: altx, shape: {kind: scalar, item_type: ASCII}}
- id: S5F2
stream: 5
function: 2
builder: s5f2_alarm_ack
body: {kind: scalar, item_type: BINARY_BYTE, enum: AlarmAck, param: ack}
- id: S5F3
stream: 5
function: 3
w: true
builder: s5f3_enable_alarm
parser: parse_s5f3
body:
kind: list
struct_name: EnableAlarmRequest
fields:
- {name: aled, shape: {kind: scalar, item_type: BINARY_BYTE}}
- {name: alid, shape: {kind: scalar, item_type: U4}}
- id: S5F4
stream: 5
function: 4
builder: s5f4_enable_alarm_ack
body: {kind: scalar, item_type: BINARY_BYTE, enum: AlarmAck, param: ack}
- id: S5F5
stream: 5
function: 5
w: true
builder: s5f5_list_alarms_request
parser: parse_s5f5
body:
kind: list_of
element: {kind: scalar, item_type: U4}
name: alids
# S5F6 is hand-written (per-row ALCD requires an active-callback API).
# =====================================================================
# S6 — Data collection
# =====================================================================
- id: S6F11
stream: 6
function: 11
w: true
builder: s6f11_event_report
parser: parse_s6f11
body:
kind: list
struct_name: EventReportMessage
fields:
- {name: dataid, shape: {kind: scalar, item_type: U4}}
- {name: ceid, shape: {kind: scalar, item_type: U4}}
- name: reports
shape:
kind: list_of
element:
kind: list
struct_name: ReportData
external_struct: true
fields:
- {name: rptid, shape: {kind: scalar, item_type: U4}}
- name: values
shape: {kind: list_of, element: {kind: scalar, item_type: ITEM}}
- id: S6F12
stream: 6
function: 12
builder: s6f12_event_report_ack
body: {kind: scalar, item_type: BINARY_BYTE, enum: EventReportAck, param: ack}
# =====================================================================
# S7 — Process programs
# =====================================================================
- id: S7F3
stream: 7
function: 3
w: true
builder: s7f3_process_program_send
parser: parse_s7f3
body:
kind: list
struct_name: ProcessProgram
fields:
- {name: ppid, shape: {kind: scalar, item_type: ASCII}}
- {name: ppbody, shape: {kind: scalar, item_type: BINARY}}
- id: S7F4
stream: 7
function: 4
builder: s7f4_process_program_ack
body: {kind: scalar, item_type: BINARY_BYTE, enum: ProcessProgramAck, param: ack}
- id: S7F5
stream: 7
function: 5
w: true
builder: s7f5_process_program_request
parser: parse_s7f5
body: {kind: scalar, item_type: ASCII, param: ppid}
- id: S7F6
stream: 7
function: 6
builder: s7f6_process_program_data
parser: parse_s7f6
body:
kind: list
struct_name: ProcessProgram
fields:
- {name: ppid, shape: {kind: scalar, item_type: ASCII}}
- {name: ppbody, shape: {kind: scalar, item_type: BINARY}}
- id: S7F19
stream: 7
function: 19
w: true
builder: s7f19_current_eppd_request
- id: S7F20
stream: 7
function: 20
builder: s7f20_current_eppd_data
parser: parse_s7f20
body:
kind: list_of
element: {kind: scalar, item_type: ASCII}
name: ppids
# =====================================================================
# S10 — Terminal services
# =====================================================================
- id: S10F1
stream: 10
function: 1
w: true
builder: s10f1_terminal_display_single
parser: parse_s10f1
body:
kind: list
struct_name: TerminalDisplay
fields:
- {name: tid, shape: {kind: scalar, item_type: BINARY_BYTE}}
- {name: text, shape: {kind: scalar, item_type: ASCII}}
- id: S10F2
stream: 10
function: 2
builder: s10f2_terminal_display_ack
body: {kind: scalar, item_type: BINARY_BYTE, enum: TerminalAck, param: ack}
- id: S10F3
stream: 10
function: 3
w: true
builder: s10f3_terminal_display_single
parser: parse_s10f3
body:
kind: list
struct_name: TerminalDisplay
fields:
- {name: tid, shape: {kind: scalar, item_type: BINARY_BYTE}}
- {name: text, shape: {kind: scalar, item_type: ASCII}}
- id: S10F4
stream: 10
function: 4
builder: s10f4_terminal_display_ack
body: {kind: scalar, item_type: BINARY_BYTE, enum: TerminalAck, param: ack}