RBC_Template 0.1.0 build 5fb9afb
Workspace master specification — safety-related railway software around an ERTMS Radio Block Centre (RBC), CENELEC EN 50128 / SIL 4
Loading...
Searching...
No Matches
RBC_Template architecture

The overall architecture of the RBC_Template workspace: layers, products, runtime view, the interfaces between products, and the rules that keep them independent. Each product's own README is the source of truth for its internals and for its interface details; this document holds only what spans products. For the safety and quality approach see ../safety/SAFETY_AND_QUALITY_PLAN.dox; for the assessment units see ../safety/CERTIFICATION_PLAN.dox.

1. What RBC_Template is

A set of independently versioned products for building, simulating and testing a redundant ERTMS/ETCS Radio Block Centre (RBC). It follows the Reference CCS Architecture (RCA) and the OCORA Safe Computing Platform (SCP) model: safety-relevant application logic is written against a platform-independent API, and the platform owns redundancy, voting, communication and safe-state handling. The C code in platform/ and application/ targets CENELEC EN 50128 / SIL 4 (MISRA C:2023). The Python and Docker material in test/ exercises that code and carries no safety rating.

2. Layers and products

flowchart TB
    subgraph APP["Application layer"]
        direction TB
        SA["RBC_SA — Specific Application<br/>site data, redundancy configuration, packaging"]
        GA["RBC_GA — Generic Application<br/>IL / CTC route logic (shared library)"]
        GP["RBC_GP — Generic Platform<br/>RBC executable: ERTMS procedures, 2oo2 A/B, site failover"]
        SA --> GA --> GP
    end

    APP -->|"PI-API (rte_flow)"| RTE

    subgraph RTE["Platform_RTE — Safe Computing Platform / RTE"]
        direction TB
        CORE["voting, cross-compare, checkpoint, safe state,<br/>channels, timers, memory ..."]
        subgraph SC[" "]
            SCD["Platform_Protocol_SafeComm<br/>SS-037 / SS-098 safe communication"]
        end
        CORE --> SC
    end

    RTE -->|"OSAdapter seams (ADR-005): OSAdapter / ProtocolAdapter"| OS

    subgraph OS["Adapter layer"]
        direction LR
        POSIX["Platform_OS_POSIX<br/>(OSAdapter)"]
        DDS["Platform_Protocol_DDS<br/>(ProtocolAdapter, stub)"]
    end

    OS --> HW["Operating system and hardware<br/>(hardware platform not chosen yet)"]

    TC["Build infrastructure:<br/>Platform_Toolchain_{MacOS, Linux, QNX, FreeRTOS}"]
    VER["Verification only (not safety-rated):<br/>test/RBC_Test_Env, RBC_Test_CommServer, RBC_Test_Sim_*"]
    VER -.-> APP
    TC -.-> RTE
Folder Product Layer Safety tier Owns
application/RBC_SA RBC_SA Specific Application Vital data, SIL 4 Site data libraries, installer packaging
application/RBC_GA RBC_GA Generic Application Vital, SIL 4 IL/CTC adaptation logic
application/RBC_GP RBC_GP Generic Platform Vital (A/B), non-vital (role C) ERTMS procedures, A/B cross-compare, site negotiation, gateway
platform/Platform_RTE Platform_RTE RTE core Vital, SIL 4 Redundancy, voting, safe state, OAL and Flow contracts
platform/protocol_adapters/Platform_Protocol_SafeComm Platform_Protocol_SafeComm RTE service Vital (SFM, CFM), non-vital (ALE, config) SS-037 / SS-098
platform/protocol_adapters/Platform_Protocol_JRU Platform_Protocol_JRU RBC_GP sub-product, implements the RTE log seam Non-vital (SIL 0), runs on Gateway RFC 5424 syslog, implements rte_osadapter_log_t; not wired to a caller yet
application/Platform_Protocol_KM114 Platform_Protocol_KM114 RBC_GP sub-product Security function; linked into A/B Subset-114 KMC-to-entity off-line key management wire format
application/Platform_Protocol_KM038 Platform_Protocol_KM038 RBC_GP sub-product Security function; no consumer Subset-038 KMC-KMC interworking wire format
application/RBC_Maintenance_Web RBC_Maintenance_Web RBC_GP sub-product Non-vital (SIL 0), runs on Gateway Status dashboard over HTTP, mTLS-gated SIL 0 software update, interim takeover-confirmation issuer; linked into RBC_GP's Gateway
services/RBC_TrainCommServer RBC_TrainCommServer Placeholder Tooling Not yet scoped - see TODO.dox
services/RBC_AI_Diagnostic_Server RBC_AI_Diagnostic_Server Placeholder Tooling Not yet scoped - see TODO.dox
platform/os_adapters/Platform_OS_POSIX Platform_OS_POSIX OSAdapter Vital, SIL 4 target POSIX/Linux OSAdapter
platform/protocol_adapters/Platform_Protocol_DDS Platform_Protocol_DDS ProtocolAdapter Stub rte_flow OSAdapter
platform/toolchains/Platform_Toolchain_* Platform_Toolchain_* Build Tooling Compiler wiring per target
test/* RBC_Test_* Verification Tooling Simulators, access-point stub, end-to-end suite

Folder names, product names and GitHub repository names are the same (repositories renamed on 2026-09-22). The grouping of products is in PRODUCT_STRUCTURE.dox.

3. Runtime view

flowchart TB
    TRAIN["Train (EVC)"]
    IL["Interlocking (IL)"]
    CTC["CTC"]

    CS["RBC_Test_CommServer<br/>(plain TCP / simulator links, rbc_wire envelope)"]
    TRAIN --> CS
    IL --> CS
    CTC --> CS

    CS -->|"ab-relay-*"| GWWEST["Role C gateways (non-vital): train, il, ctc, util — WEST site"]
    CS -->|"ab-relay-*"| GWEAST["Role C gateways (non-vital): train, il, ctc, util — EAST site"]

    subgraph WEST["WEST site"]
        AW["A"] <-->|"ab-peer + ab-crosscompare (2oo2)"| BW["B"]
    end
    subgraph EAST["EAST site"]
        AE["A"] <-->|"ab-peer + ab-crosscompare (2oo2)"| BE["B"]
    end

    GWWEST --> WEST
    GWEAST --> EAST
    WEST <-->|"inter-site links A-A and B-B (site role)"| EAST
  • Per site (WEST, EAST): role A, role B and the role C gateway service processes (train, il, ctc, status). There is no standalone SITE role: each of A and B runs Platform_RTE's site-role service (rte_site_role, ADR-040) on its own inter-site link, and A and B must agree on the result. A and B form the 2oo2 vital pair of a site (they cross-compare their train-session tables every cycle); the two sites are ONLINE and STANDBY and swap on failure. End-to-end description: RBC_GP: Site redundancy and A/B agreement.
  • Redundancy topology, replica count, quorum and standby mode (hot, warm, cold) come from the framework configuration file, not from application code. The application registers what it supports and which state must survive a promotion. The Platform decides; the application only declares.
  • Safe state: on a cross-compare disagreement, a checkpoint timeout or a voting failure the Platform enters the safe state itself; applications register a cleanup handler. RBC_GP still calls RTE_SAFESTATE itself for its other fault reactions (A/B site-role disagreement, persistent A/B cycle skew, CRC-64 corruption of the cross-compare sample).

4. Interfaces between products

These are the interfaces another product may rely on. Each product README lists its own in detail; this catalog is the cross-product index.

Interface Provided by Used by Form Stability
PI-API (rte_flow_*) Platform_RTE RBC_GP, RBC_GA C headers rte/oal/flow/ Target public API of the platform
Platform services (app manager, safe state, voter, cross-comparator, checkpoint, site role service and dual negotiator) Platform_RTE RBC_GP C headers rte/app, rte/redundancy Used directly today; narrowing to PI-API is tracked in TODO.dox
OSAdapter seams (one vtable per OAL service, rte_osadapter_flow_t, rte_osadapter_channel_service_t) Platform_RTE defines; Platform_OS_POSIX and Platform_Protocol_DDS implement Platform_RTE C vtables (ADR-005) Stable contract
Capability declaration and state registration Platform_RTE (rte_redundancy_config, rte_state_transfer) RBC_GP declares C API Stable
Redundancy configuration Platform_RTE parses a JSON file (RBC_GP: etc/config/<role>_<site>.json, fallback etc/config/redundancy.json, override RTE_REDUNDANCY_CONFIG_FILE) Integrator writes JSON file Stable schema
GA interface (ga_interface.h) RBC_GP RBC_GA Bare init call GP to GA, callbacks and context snapshots GA to GP; GP and GA are shared libraries built against dummies of each other Versioned boundary
Site data contracts (ab_siteGP.h, ab_siteGA.h) RBC_GP and RBC_GA define RBC_SA implements C headers plus generated tables Versioned per project
Safe communication (safecomm::safety, ::cfm, ::ale, ::config) Platform_Protocol_SafeComm Platform_RTE consumers, gateway C libraries In build-out
RBC wire protocol (rbc_envelope_t, 512 bytes) RBC_GP RBC_Test_Sim_*, RBC_Test_CommServer Byte layout Hand-mirrored in RBC_Test_Sim_Core/rbc_wire.py
Safe communication links (train: Subset-037, IL: Subset-098 profile) Platform_Protocol_SafeComm, terminated in RBC_GP A/B Train, IL, RBC_Test_CommServer, gateways SaF frames carrying the envelope Train link terminated in A/B, off by default; IL link not yet: SAFE_COMM_INTEGRATION.dox
Key management wire format (Subset-114 KMC-to-entity, Subset-038 KMC-KMC) Platform_Protocol_KM114, Platform_Protocol_KM038 Not yet wired into any RBC product C libraries, off-line message encode/decode/MAC Wire format done; no consumer yet — see TODO.dox
Installer RBC_SA Deployment Self-extracting shell installer plus packaging.conf Stable
Toolchain files Platform_Toolchain_* Any CMake build -DCMAKE_TOOLCHAIN_FILE= Stable
Artifacts (dist/<platform>/, wheels, Conan packages) Every product Downstream products See section 6 Stable

5. Dependency rules

  1. Dependencies point downward in the diagram and never reverse. A change in a depended-on product that breaks a consumer is the consumer's job to absorb.
  2. application/* may depend on platform/*. platform/* never depends on application/*. test/* may depend on anything and nothing depends on test/*.
  3. Applications reach the OS and the network only through Platform_RTE, never through an OSAdapter directly. Platform_OS_POSIX and Platform_Protocol_DDS depend only on Platform_RTE. Known deviation:** RBC_GP (A/B and role C) and RBC_GA still use the C standard library directly (<stdio.h>, <stdlib.h>, snprintf, getenv, file reads for configuration). Nothing in them calls the OS or the network outside RTE, but a SIL 4 assessment will count the library calls as deviations from the MISRA standard-library rules (Rules 21.6 and 21.8 in the MISRA C:2012 numbering of the current screening), and the platform-only rule. ../../safety_quality/REVIEW_2026-09-21.dox finding A2; the vital A/B half is now recorded as a formal deviation, construct by construct, with justification and compensating measures, in application/RBC_GP/docs/MISRA_COMPLIANCE_REPORT.dox.
  4. RBC_GA calls RBC_GP only through ga_interface.h. RBC_GA and RBC_SA also read RBC_GP headers at build time; that shared build-time reach is the one place where the direction is not strict, and it is the reason the interface is versioned.
  5. safecomm::safety has no dependency on the platform. safecomm::cfm uses the OAL. Nothing in Platform_Protocol_SafeComm depends on the RBC applications.
  6. Vital code never depends on non-vital code. Non-vital code (gateway, ALE, RBC_Test_CommServer) carries bytes it cannot authenticate; the vital side verifies everything it receives.

6. Building blocks shared by all products

  • Layout and paths. Projects find each other by the workspace layout (application/* finds ../../platform/Platform_RTE). A flat sibling checkout of the old repository names still works as a fallback in most projects. Docker builds use the workspace root as context and keep the same layout inside the image.
  • Two consumption paths, both maintained. Every C project installs to dist/<platform>/ and is consumed with find_package(). Every Python project builds a wheel into dist/ and is consumed with pip --find-links. The same products also have Conan recipes. A change that breaks either path is a regression.
  • Configuration is files. Every product keeps its configuration under its own etc/.
  • Product versions. Each product has a VERSION file; releases are git tags. An RTE release is a tuple of the framework, OSAdapter and safe-communication tags.

7. Where to read next

Need Document
Safety and quality approach ../safety/SAFETY_AND_QUALITY_PLAN.dox
Assessment units, ISA and NoBo ../safety/CERTIFICATION_PLAN.dox
RCA / OCORA mapping and PI-API surface ../rca/RCA_CONCEPT.dox, ../rca/RCA-OCORA-PI-API.dox
Every product and its own documentation site Subproducts page (Related Pages)
Product breakdown (hierarchy, catalogue, dependencies) PRODUCT_STRUCTURE.dox
Logical breakdown and hardware allocation (management view, Capella input) LOGICAL_ARCHITECTURE_AND_HW_ALLOCATION.dox
MBSE model ../../architecture/capella/
Tools needed to build ../../REQUIREMENTS.dox
History of workspace decisions WORKSPACE_HISTORY.dox
A product its own README, then its CLAUDE.md and docs/