From a348e7dc358941ba9175ffdc3cef1a9069dc647b Mon Sep 17 00:00:00 2001 From: Matt <47545907+SoundMatt@users.noreply.github.com> Date: Sun, 2 Aug 2026 04:18:45 -0700 Subject: [PATCH] =?UTF-8?q?docs:=20v5.2.0=20=E2=80=94=20extract=20and=20fo?= =?UTF-8?q?rmally=20reference=20every=20TC18=20SHOULD/MAY=20clause?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Mirrors c-RCP's and cpp-RCP's own identical audits. Individually classified all 51 non-legal SHOULD/MAY occurrences in TC18. 7 already-implemented optional capabilities got a real tc18 citation added to their existing requirement entry (0/608 requirements had one before this pass). The non-testable lines are individually cited in new docs/TC18-NON-NORMATIVE-CLAUSES.md. Honestly flags 4 MAY-described capabilities as genuinely uncertain rather than papering over them with a citation — most notably a possible 32-bit-vs-48-bit time-domain conflation in the Timed-request readiness check (REQ-TIME-002/003), the same bug class found and fixed this session in go-RCP's conditional-request envelopes. Not fixed here; recorded for its own dedicated investigation. No code behavior changed. Signed-off-by: Matt <47545907+SoundMatt@users.noreply.github.com> --- .fusa-reqs.json | 21 +++++++---- CHANGELOG.md | 25 +++++++++++++ Cargo.lock | 2 +- Cargo.toml | 2 +- docs/TC18-NON-NORMATIVE-CLAUSES.md | 60 ++++++++++++++++++++++++++++++ 5 files changed, 101 insertions(+), 9 deletions(-) create mode 100644 docs/TC18-NON-NORMATIVE-CLAUSES.md diff --git a/.fusa-reqs.json b/.fusa-reqs.json index 78b2a97..a6a4107 100644 --- a/.fusa-reqs.json +++ b/.fusa-reqs.json @@ -296,7 +296,8 @@ "standard": "iso26262", "level": "HLR", "asil": "ASIL-B", - "verificationMethod": "test" + "verificationMethod": "test", + "tc18": "§12.4 (\"The RC Server may support different power modes\"), TC18.txt L2268" }, { "id": "REQ-PWR-002", @@ -2366,7 +2367,8 @@ "standard": "iso26262", "level": "HLR", "asil": "ASIL-B", - "verificationMethod": "test" + "verificationMethod": "test", + "tc18": "§12.3 (\"The three lifecycle states the device may be in are...\"), TC18.txt L2063" }, { "id": "REQ-LIFE-002", @@ -3176,7 +3178,8 @@ "standard": "iso26262", "level": "HLR", "asil": "ASIL-B", - "verificationMethod": "test" + "verificationMethod": "test", + "tc18": "§13.7.3.1 (\"the SPI endpoint may support up to 6 pre-configurable sets of SPI configurations\"), TC18.txt L4192" }, { "id": "REQ-SPI-006", @@ -3472,7 +3475,8 @@ { "id": "REQ-ADC-007", "title": "resolve_adc_sample_window_ticks chains adc_sample_interval, adc_avg_intervals_per_request, and adc_combine_avg_values into a total elapsed tick count, and never panics", - "text": "resolve_adc_sample_window_ticks multiplies adc_avg_intervals_per_request by adc_combine_avg_values by adc_sample_interval to produce the total elapsed tick count one combined result takes to produce, using checked (never-wrapping, never-panicking) arithmetic throughout including at the all-MAX field-width boundary, and never panics for any sampled AdcAveragingConfig" + "text": "resolve_adc_sample_window_ticks multiplies adc_avg_intervals_per_request by adc_combine_avg_values by adc_sample_interval to produce the total elapsed tick count one combined result takes to produce, using checked (never-wrapping, never-panicking) arithmetic throughout including at the all-MAX field-width boundary, and never panics for any sampled AdcAveragingConfig", + "tc18": "§13.7.9.2 (\"an implementation may decide to fix\" the samples-per-interval field read-only; this implementation instead makes it writable, the more general of the two spec-permitted choices), TC18.txt L5040" }, { "id": "REQ-PWM-007", @@ -3653,7 +3657,8 @@ "standard": "iso26262", "level": "HLR", "asil": "ASIL-B", - "verificationMethod": "test" + "verificationMethod": "test", + "tc18": "§11.2.2.3 (\"Each endpoint may be configured to start a request upon receiving a selected trigger signal\"), TC18.txt L1413" }, { "id": "REQ-TRIG-002", @@ -3788,7 +3793,8 @@ "standard": "iso26262", "level": "HLR", "asil": "ASIL-B", - "verificationMethod": "test" + "verificationMethod": "test", + "tc18": "§13.2 (\"[an implementation] may support only a lower number of sequencers\"), TC18.txt L3473" }, { "id": "REQ-SEQ-002", @@ -4184,7 +4190,8 @@ "standard": "iso26262", "level": "HLR", "asil": "ASIL-B", - "verificationMethod": "test" + "verificationMethod": "test", + "tc18": "§12.7.7 (\"a safe state may be enforced. The safe state to enter can be chosen via the Safety_Measure parameter\"), TC18.txt L2935" }, { "id": "REQ-SAFEMEAS-002", diff --git a/CHANGELOG.md b/CHANGELOG.md index 4540364..59b8415 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,31 @@ OPEN Alliance TC18 core replacement; from `v1.0.0` on, each entry is a real release. See `docs/SEMVER.md` for the versioning scheme, including why a wire-format change is a MAJOR bump even when it is a fix. +## v5.2.0 (2026-08-02 SHOULD/MAY extraction + references) — closed + +Mirrors c-RCP's and cpp-RCP's own identical SHOULD/MAY audits. Grepped +the full TC18 spec text for every SHOULD (12) and MAY (44) occurrence, +excluded 6 legal-boilerplate hits, and individually classified the +remaining 51. Seven already-implemented optional capabilities got a real +`tc18` citation added to their existing requirement entry — a field this +crate's `.fusa-reqs.json` had never used before (0/608 requirements cited +TC18 prior to this pass). The non-testable lines are individually cited +in new `docs/TC18-NON-NORMATIVE-CLAUSES.md`. + +This pass also honestly flags four MAY-described capabilities as +genuinely uncertain rather than papering over them with a citation — +most notably, `REQ-TIME-002`/`REQ-TIME-003`'s Timed-request readiness +check uses `AvtpTimestamp`, a 32-bit/~4.3-second-rollover type, for what +TC18 §11.2.2.5 defines as a 48-bit/3.25-day-rollover `presentation_time` +value — the same class of time-domain conflation bug found and fixed +this session in go-RCP's conditional-request envelopes. Not fixed here; +recorded for its own dedicated investigation. The other three flagged +gaps (multi-request-per-frame's citation, the EP_USED bit, and +integrated-PHY-via-MDIO) are recorded the same way. + +No code behavior changed. A fuller MUST-clause citation backfill remains +separate, larger, future work. + ## v5.0.0 (2026-07-31 TC18-conformant power-mode model + register-map config tables) — closed **Breaking**, on the wire for three register-map config-table row types and diff --git a/Cargo.lock b/Cargo.lock index eae72f4..7205076 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -333,7 +333,7 @@ checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf" [[package]] name = "rcp" -version = "5.1.0" +version = "5.2.0" dependencies = [ "async-trait", "base64", diff --git a/Cargo.toml b/Cargo.toml index 6c67539..a1643e9 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "rcp" -version = "5.1.0" +version = "5.2.0" edition = "2021" rust-version = "1.75" license = "MPL-2.0" diff --git a/docs/TC18-NON-NORMATIVE-CLAUSES.md b/docs/TC18-NON-NORMATIVE-CLAUSES.md new file mode 100644 index 0000000..582cdfb --- /dev/null +++ b/docs/TC18-NON-NORMATIVE-CLAUSES.md @@ -0,0 +1,60 @@ +# TC18 SHOULD/MAY clauses with no corresponding requirement + +Companion to `.fusa-reqs.json`'s MUST/SHALL requirement catalog. Mirrors +c-RCP's and cpp-RCP's own identical audits (see those repos' +`docs/TC18-NON-NORMATIVE-CLAUSES.md` and ROADMAP milestones). Every +SHOULD/MAY occurrence in TC18 is accounted for here or via an existing +`REQ-*` entry's new `tc18` citation field (introduced by this pass — this +repo's schema previously had no citation field at all). + +No spec text is reproduced verbatim; each line is paraphrased and cited +by section/`pdftotext`-extraction line reference. + +**Depth note:** like cpp-RCP's pass, this mirrors c-RCP's methodology at +a lighter verification depth given this repo's near-zero prior citation +density (0/608 requirements had a `tc18` citation before this pass). +Four MAY clauses below are flagged ⚠ as genuinely uncertain or +gap-suggesting rather than cited — they need their own follow-up +investigation. A fuller MUST-clause citation backfill remains separate, +larger, future work. + +## SHOULD (10, all non-testable — identical disposition to every x-RCP repo, this is about the standard's own text) + +Six §2 design-goal statements (L773/790/795/798/803/805), two +client-request-composition advice pieces for repetitive compound/ +compound-wait requests (L1213/L1312), one client-config-authoring +byte_bus_id/endpoint-type-consistency advice (L2988), one ISELED +hardware-calibration guideline (L5525, moot here — this repo does not +implement an ISELED endpoint). None are library-testable; see c-RCP's +own document for the identical per-line reasoning. + +## MAY — implemented and now cited (7) + +`REQ-PWR-001` (power modes, L2268), `REQ-LIFE-001` (three lifecycle +states, L2063), `REQ-SPI-005` (SPI 6 channels, L4192), `REQ-ADC-007` +(samples-per-interval R/W choice, L5040), `REQ-TRIG-001` (Triggered +requests exist as an optional feature, L1413), `REQ-SEQ-001` (fewer +sequencers permitted, L3473), `REQ-SAFEMEAS-001` (Safety_Measure-driven +safe state, L2935). + +## MAY — genuinely uncertain / not yet distinctly resolved (4, ⚠ needs follow-up) + +| § | Citation | Paraphrase | Finding | +|---|---|---|---| +| §11.2.2.5 | TC18.txt L1649 | RC Server may reject a request whose `presentation_time` is too far in the future | ⚠ **Ambiguous, not cited**: `REQ-TIME-002`/`REQ-TIME-003` (`TimedExecutionTime`/`is_timed_request_ready`) implement execution-*readiness* (has current time passed the scheduled time) via `AvtpTimestamp`, a **32-bit**, ~4.3-second-rollover type — but this is a different concern from admission control (reject an overly-*future* request), and TC18's real presentation_time for a Timed request under ACF_GBB is a **48-bit** value rolling over every 3.25 days (§11.2.2.5 Figure 12), not the 32-bit TSCF `avtp_timestamp` domain. Whether `AvtpTimestamp` is actually the right type for this, or conflates two distinct spec-defined time domains (the same bug class found and fixed this session in go-RCP's request/envelope.go), was not confirmed. Needs its own dedicated investigation before either citing or fixing. | +| §12.9.1.1 | TC18.txt L3220 | An RCP frame may include multiple ACF-types (requests) | ⚠ **No single clean citation found**: multi-frame/split-frame logic exists in `mock.rs`/`udp.rs` but no distinctly-titled requirement was found covering the general "parse and dispatch N ACF messages from one AVTPDU" capability the way c-RCP's `REQ-MOCK-019` or cpp-RCP's `REQ-L2-007` do. May already be covered under a differently-worded existing requirement — needs a closer read, not assumed absent. | +| §13.2 | TC18.txt L3502 | An endpoint may be used or not used in a specific RC Server instantiation (EP_USED bit) | ⚠ **Not found**: no `ep_used`/`EpUsed` concept found in any searched file. Same finding as cpp-RCP; c-RCP is so far the only repo confirmed to model this bit. | +| §13.7.13.1 | TC18.txt L5631 | An RC Server with an integrated PHY may allow access to it via the MDIO EP | ⚠ **Not addressed**: `src/mdio.rs`'s functional-config model doesn't discuss this deployment mode the way c-RCP's `ep_mdio.h` does. Likely fine by the same reasoning (register-map access doesn't inherently require validating a physical pin mapping) but not independently confirmed. | + +## MAY — descriptive/out-of-scope (27, identical disposition to c-RCP's/cpp-RCP's own audits) + +L640 (Edge Node PTP/MACsec — L1/L2 topology, out of RCP-wire scope), +L909, L1024, L1025, L1588, L1943 (gPTP sync generally — implemented via +this repo's own timestamp/clock handling, no single citable requirement), +L2060, L2062, L2244, L2289, L2355, L2385, L2405, L2565, L2668, L2984, +L2986, L2989, L3197, L3206, L3227, L3252, L4323, L5035, L5164, L5358 — +each is descriptive prose restating an architectural fact from a +different angle, a client-side/hardware-deployment choice outside +library scope, or a non-closed-list permission. See c-RCP's identical +document for the per-line paraphrase and reasoning — the spec text and +its non-normative character don't change per implementation.