diff --git a/BUILD b/BUILD index 6ee8d2e34c..05f6abdd5f 100644 --- a/BUILD +++ b/BUILD @@ -19,6 +19,10 @@ load("//:project_config.bzl", "PROJECT_CONFIG") load(":qemu.bzl", "qemu_aarch64") docs( + code_targets = [ + "//score/flatbuffers/bazel:starlark_rule_links", + "//score/flatbuffers:flatbufferutils", + ], data = [ "@score_platform//:needs_json", "@score_process//:needs_json", diff --git a/MODULE.bazel b/MODULE.bazel index 94d3ad66b7..67ab7737d0 100644 --- a/MODULE.bazel +++ b/MODULE.bazel @@ -95,8 +95,8 @@ bazel_dep(name = "score_toolchains_rust", version = "0.10.0", dev_dependency = T ## Custom Module Loading -bazel_dep(name = "score_docs_as_code", version = "4.6.1", dev_dependency = True) -bazel_dep(name = "score_process", version = "2.0.2", dev_dependency = True) +bazel_dep(name = "score_docs_as_code", version = "7.0.1", dev_dependency = True) +bazel_dep(name = "score_process", version = "2.0.3", dev_dependency = True) bazel_dep(name = "score_tooling", version = "1.3.1", dev_dependency = True) # score_tooling declares trlc and lobster as regular bazel_deps with their own @@ -116,17 +116,16 @@ git_override( bazel_dep(name = "score_platform", version = "0.6.2", dev_dependency = True) -# Needed until a release of score_platform includes -# https://github.com/eclipse-score/score/pull/3071 (merged to main). +# Interface definition for flatbuffers architecture git_override( module_name = "score_platform", - commit = "c97388c6da1f5b3233d4b73bffa196ff75e801cd", + commit = "7a77d2d124da83a2812dc12ba8b0a2e0d2b74b04", remote = "https://github.com/eclipse-score/score", ) ## Configure the python toolchain -bazel_dep(name = "rules_python", version = "1.8.3") +bazel_dep(name = "rules_python", version = "1.8.5") PYTHON_VERSION = "3.12" diff --git a/MODULE.bazel.lock b/MODULE.bazel.lock index 0b9ea862bf..8d3552a4af 100644 --- a/MODULE.bazel.lock +++ b/MODULE.bazel.lock @@ -423,7 +423,8 @@ "https://bcr.bazel.build/modules/rules_python/1.4.1/MODULE.bazel": "8991ad45bdc25018301d6b7e1d3626afc3c8af8aaf4bc04f23d0b99c938b73a6", "https://bcr.bazel.build/modules/rules_python/1.5.1/MODULE.bazel": "acfe65880942d44a69129d4c5c3122d57baaf3edf58ae5a6bd4edea114906bf5", "https://bcr.bazel.build/modules/rules_python/1.8.3/MODULE.bazel": "f343e159b59701334be3914416b9f1b72845801ba47920fcb288af4ce8c5cce3", - "https://bcr.bazel.build/modules/rules_python/1.8.3/source.json": "e5439f308e3c6f79f318a0f87108db46fc575be89370c3dfb3f7e0eaa571a3f8", + "https://bcr.bazel.build/modules/rules_python/1.8.5/MODULE.bazel": "28b2d79ed8368d7d45b34bacc220e3c0b99cbcd9392641961b849e4c3f55dd30", + "https://bcr.bazel.build/modules/rules_python/1.8.5/source.json": "e261b03c8804f2582c9536013f987e1ea105a2b38c238aa2ac8f98fc34c8b18a", "https://bcr.bazel.build/modules/rules_python_gazelle_plugin/1.5.1/MODULE.bazel": "371440271705f949a1b51ca875c7d00ce9057e540fdbf26311445cc10810974b", "https://bcr.bazel.build/modules/rules_python_gazelle_plugin/1.5.1/source.json": "c52e4d2229fbd92b658bf60a7638e79b96525e8f7ed6c59036b4827cade9e430", "https://bcr.bazel.build/modules/rules_robolectric/4.14.1.2/MODULE.bazel": "d44fec647d0aeb67b9f3b980cf68ba634976f3ae7ccd6c07d790b59b87a4f251", @@ -442,6 +443,8 @@ "https://bcr.bazel.build/modules/rules_swift/1.18.0/MODULE.bazel": "a6aba73625d0dc64c7b4a1e831549b6e375fbddb9d2dde9d80c9de6ec45b24c9", "https://bcr.bazel.build/modules/rules_swift/2.1.1/MODULE.bazel": "494900a80f944fc7aa61500c2073d9729dff0b764f0e89b824eb746959bc1046", "https://bcr.bazel.build/modules/rules_swift/2.1.1/source.json": "40fc69dfaac64deddbb75bd99cdac55f4427d9ca0afbe408576a65428427a186", + "https://bcr.bazel.build/modules/sphinxdocs/2.2.0/MODULE.bazel": "e046c573919d72605d62c352a08d9223a10aafef3a7cb70d0fe253ebdd97019e", + "https://bcr.bazel.build/modules/sphinxdocs/2.2.0/source.json": "b1da19a3d14a1dd8aa6a9ccaedc42bbe0313c8160a77ba5cca336cca1315298d", "https://bcr.bazel.build/modules/stardoc/0.5.0/MODULE.bazel": "f9f1f46ba8d9c3362648eea571c6f9100680efc44913618811b58cc9c02cd678", "https://bcr.bazel.build/modules/stardoc/0.5.1/MODULE.bazel": "1a05d92974d0c122f5ccf09291442580317cdd859f07a8655f1db9a60374f9f8", "https://bcr.bazel.build/modules/stardoc/0.5.3/MODULE.bazel": "c7f6948dae6999bf0db32c1858ae345f112cacf98f174c7a8bb707e41b974f1c", @@ -832,6 +835,7 @@ "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/rules_python/1.4.1/MODULE.bazel": "not found", "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/rules_python/1.5.1/MODULE.bazel": "not found", "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/rules_python/1.8.3/MODULE.bazel": "not found", + "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/rules_python/1.8.5/MODULE.bazel": "not found", "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/rules_python_gazelle_plugin/1.5.1/MODULE.bazel": "not found", "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/rules_robolectric/4.14.1.2/MODULE.bazel": "not found", "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/rules_rust/0.56.0/MODULE.bazel": "not found", @@ -864,8 +868,8 @@ "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/score_crates/0.0.10/source.json": "9fb86963b62475c8fffb6432749a547d52d728ff829b48679fa091f0dfd338a7", "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/score_dash_license_checker/0.1.1/MODULE.bazel": "76681dbd2d45b5c540869a2337174086c56c54953aab1d02cd878b59d31d13a5", "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/score_devcontainer/1.7.0/MODULE.bazel": "f9a5971fbd05f0ed14e7a373dbf58af72a5c58d081537a75c314daaf61c92ae9", - "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/score_devcontainer/1.8.0/MODULE.bazel": "89f855b94d041d2e61ff9667562fb4539c146249f6fb4c5dddf3d13bb9064aa7", - "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/score_devcontainer/1.8.0/source.json": "ef316fad71fdbd53daf43fc0a82fbc7c293908a2712214ff79134c177d028024", + "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/score_devcontainer/1.9.0/MODULE.bazel": "2a04a354eb7a77d478bb43ba20b1dac0758af858172a760e4290621bef1a2f28", + "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/score_devcontainer/1.9.0/source.json": "6f72c780f1fb167be7cbc01801b86534a9e7102003168dcdf2c8886cfb1bb209", "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/score_docs_as_code/0.3.3/MODULE.bazel": "95d2b7d44d461c1cf9bd016605f740716fd4ea1303f5f2ed93de3566b90feb1b", "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/score_docs_as_code/1.0.0-RC1/MODULE.bazel": "e118b5cbdc453cde83b5ce481107d8e4a713d3458550b9d10445046d4bba2ff3", "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/score_docs_as_code/1.0.0/MODULE.bazel": "a3ad204b7412c02a899034d78de62b5549bafba5530a256d1007cb3f4ed20a11", @@ -876,8 +880,9 @@ "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/score_docs_as_code/2.0.3/MODULE.bazel": "9b945514727190d4c381d8965b972884ba04ce105260ffd2b3c9df51f206ebfe", "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/score_docs_as_code/4.5.0/MODULE.bazel": "4cfe52fe8b8dbeaf7e87500036391da278f72f1c2b41b689ffdd4337196dd8fe", "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/score_docs_as_code/4.6.0/MODULE.bazel": "d5fbfed7b9bd65f10830e2290045dea639a8cfcaf9f9f0f7a1b12888c14e7d2b", - "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/score_docs_as_code/4.6.1/MODULE.bazel": "0dae734ea8a99970a7417829b3115af02717b29f0fc40a8ebd3c1afcc71e1e21", - "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/score_docs_as_code/4.6.1/source.json": "3299daf219b15ba4aff6ca801385abebe0aaf364f71e391cd76cf9d38f3741f6", + "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/score_docs_as_code/6.0.0/MODULE.bazel": "ab2af2d8fab73e4512d2e2bd399a64d10c5c5463388322f7025637b13ec7585c", + "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/score_docs_as_code/7.0.1/MODULE.bazel": "8ca16bc1143f4834e1ad061ddebb3b57dac966d46f890a07829f055dbb3a3d15", + "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/score_docs_as_code/7.0.1/source.json": "bf02ecf6e0bb5532d0654d3411fc7cbd97172f7e0daf979d901e83248a92991e", "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/score_format_checker/0.1.1/MODULE.bazel": "1acc254faa90e9f97b79ac69af25b6c21c561f8d6079914f6352b9b20d26bd37", "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/score_process/1.0.4/MODULE.bazel": "f74302cb90a7c4878db302276afae82966878099861dcfca3ef43256131dab52", "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/score_process/1.0.5/MODULE.bazel": "ed17c232ebd65e9d50fd5c1832f90f95ffe95b2a1113d63a176295a2af64d111", @@ -889,8 +894,8 @@ "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/score_process/1.3.2/MODULE.bazel": "a32390ef217cef9a811408b0a1c5aeed1398c377aa846f5d5416d7b95b4e4366", "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/score_process/1.6.0/MODULE.bazel": "2496bc24311f69f49449ee85d8bb38e3b970cbfcf10d0a7f19b2d5262ce80e8d", "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/score_process/2.0.1/MODULE.bazel": "88bff0ed46da79d87f8c441a6bf6b760ee7c194b282e7e54a8b7db6ea2354db9", - "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/score_process/2.0.2/MODULE.bazel": "6d2b227bb6880e9f6871cc8cf94c83399e35c188424f7e9b826262de8149ed43", - "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/score_process/2.0.2/source.json": "5ae55f0dabcddeb5bfae16ce480e2c065f907d2b0ed6a8e4ed7409b259b004ee", + "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/score_process/2.0.3/MODULE.bazel": "d9359f1cb7e460a5eb6b7e5d2185bcc6ed7c9f4a31f560d6a703549ca6366ed7", + "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/score_process/2.0.3/source.json": "0ea635f75ded5225494b709a441488f80be0db0ded4a9786367477ecdbcf42b0", "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/score_python_basics/0.3.2/MODULE.bazel": "f25490f64035a0e3a0d53ad9cb6164e8325ce6cf2a7ee68c6ae153840cb2497e", "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/score_python_basics/0.3.4/MODULE.bazel": "53bd16dfbb1fb8ecf6822fb26f9f4e8333bac7b14d12bb02bf84078063820a31", "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/score_qnx_unit_tests/0.2.0/MODULE.bazel": "aaffff67916dd058737aac8e04368f12b214e7646ff58adbab48e6429d1a5410", @@ -906,6 +911,7 @@ "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/score_tooling/1.1.2/MODULE.bazel": "56d08309931cfad67c2b6691207bb5f761a3946830d620c630d2436630e6b499", "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/score_tooling/1.3.1/MODULE.bazel": "4ce18de0fdfb447ba750b98febb24e12471862cbbd5d08f5f683f27886767367", "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/score_tooling/1.3.1/source.json": "94e50fa631dffe1eea1a900ed0e472c479f90962faf8f2b6bc6142c506f4ff98", + "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/sphinxdocs/2.2.0/MODULE.bazel": "not found", "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/stardoc/0.5.0/MODULE.bazel": "not found", "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/stardoc/0.5.1/MODULE.bazel": "not found", "https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/modules/stardoc/0.5.3/MODULE.bazel": "not found", @@ -2457,7 +2463,7 @@ "@@rules_python+//python/extensions:config.bzl%config": { "general": { "bzlTransitiveDigest": "TRGIl0CDmorwyNiblOYyhWuyKzi/kWFHT2uIofq7o9Y=", - "usagesDigest": "HZ99ezJBkgjKcxXQ3OBxGgesUIMF6eg7E0TUNOait2I=", + "usagesDigest": "lDbpRfhoWmZCHSaNxwZv/8fF2y0wu2th0G0f/uqX7VM=", "recordedFileInputs": {}, "recordedDirentsInputs": {}, "envVariables": {}, @@ -2692,7 +2698,7 @@ "@@rules_python+//python/uv:uv.bzl%uv": { "general": { "bzlTransitiveDigest": "ijW9KS7qsIY+yBVvJ+Nr1mzwQox09j13DnE3iIwaeTM=", - "usagesDigest": "V6cPO5U+Pjet8j7Hg3jFk0k71HhbklpxIVEOGvFSnGo=", + "usagesDigest": "uQTBbUznZw5QbQpT5wBV/9G50SWy2bbs71OLoidyIG8=", "recordedFileInputs": {}, "recordedDirentsInputs": {}, "envVariables": {}, @@ -9816,7 +9822,7 @@ }, "@@score_bazel_tools_cc+//third_party:extensions.bzl%rules_python_pip_hub": { "general": { - "bzlTransitiveDigest": "CbMLgqnyZUoIquJWtnP1CiQurJskkZU0pYwOaFOx51Y=", + "bzlTransitiveDigest": "0GtHtP/Cq5COo0Le4EOEdPZFNuSL/G5HWrhbCt9KuXA=", "usagesDigest": "+R/amEJVckS++BDZJeRqyMgNukHUula12//Pxk9ndw8=", "recordedFileInputs": {}, "recordedDirentsInputs": {}, @@ -9967,7 +9973,7 @@ }, "@@score_bazel_tools_python+//third_party:extensions.bzl%rules_python_pip_hub": { "general": { - "bzlTransitiveDigest": "3d78xRj4EuBc/sPfJO5HBceMlTc1iYQjpfbr7IVMX58=", + "bzlTransitiveDigest": "1OZHf2YCGy/SmbnOq4zf+Z4Jih4Lik5zXPZlZDR2BAM=", "usagesDigest": "uHFd59qb7YF4jrGBUVBPFPMJw8NV8NZzfzv97EkHf9g=", "recordedFileInputs": {}, "recordedDirentsInputs": {}, diff --git a/docs/baselibs/components/containers_rust/docs/requirements/index.rst b/docs/baselibs/components/containers_rust/docs/requirements/index.rst index de19cf27d9..29374d80b0 100644 --- a/docs/baselibs/components/containers_rust/docs/requirements/index.rst +++ b/docs/baselibs/components/containers_rust/docs/requirements/index.rst @@ -42,7 +42,6 @@ Functional Requirements :security: NO :safety: ASIL_B :satisfied_by: comp__baselibs_containers_rust[version==1] - :belongs_to: comp__baselibs_containers_rust[version==1] :status: valid :version: 1 @@ -54,7 +53,6 @@ Functional Requirements :security: NO :safety: ASIL_B :satisfied_by: comp__baselibs_containers_rust[version==1] - :belongs_to: comp__baselibs_containers_rust[version==1] :status: valid :version: 1 @@ -68,7 +66,6 @@ Functional Requirements :security: NO :safety: ASIL_B :satisfied_by: comp__baselibs_containers_rust[version==1] - :belongs_to: comp__baselibs_containers_rust[version==1] :status: valid :version: 1 @@ -80,7 +77,6 @@ Functional Requirements :security: NO :safety: ASIL_B :satisfied_by: comp__baselibs_containers_rust[version==1] - :belongs_to: comp__baselibs_containers_rust[version==1] :status: valid :version: 1 @@ -94,7 +90,6 @@ Functional Requirements :security: NO :safety: ASIL_B :satisfied_by: comp__baselibs_containers_rust[version==1] - :belongs_to: comp__baselibs_containers_rust[version==1] :status: valid :version: 1 @@ -106,7 +101,6 @@ Functional Requirements :security: NO :safety: ASIL_B :satisfied_by: comp__baselibs_containers_rust[version==1] - :belongs_to: comp__baselibs_containers_rust[version==1] :status: valid :version: 1 @@ -120,7 +114,6 @@ Functional Requirements :security: NO :safety: ASIL_B :satisfied_by: comp__baselibs_containers_rust[version==1] - :belongs_to: comp__baselibs_containers_rust[version==1] :status: valid :version: 1 @@ -132,7 +125,6 @@ Functional Requirements :security: NO :safety: ASIL_B :satisfied_by: comp__baselibs_containers_rust[version==1] - :belongs_to: comp__baselibs_containers_rust[version==1] :status: valid :version: 1 @@ -146,7 +138,6 @@ Functional Requirements :security: NO :safety: ASIL_B :satisfied_by: comp__baselibs_containers_rust[version==1] - :belongs_to: comp__baselibs_containers_rust[version==1] :status: valid :version: 1 @@ -158,7 +149,6 @@ Functional Requirements :security: NO :safety: ASIL_B :satisfied_by: comp__baselibs_containers_rust[version==1] - :belongs_to: comp__baselibs_containers_rust[version==1] :status: valid :version: 1 @@ -172,7 +162,6 @@ Functional Requirements :security: NO :safety: ASIL_B :satisfied_by: comp__baselibs_containers_rust[version==1] - :belongs_to: comp__baselibs_containers_rust[version==1] :status: valid :version: 1 @@ -184,7 +173,6 @@ Functional Requirements :security: NO :safety: ASIL_B :satisfied_by: comp__baselibs_containers_rust[version==1] - :belongs_to: comp__baselibs_containers_rust[version==1] :status: valid :version: 1 @@ -198,7 +186,6 @@ Functional Requirements :security: NO :safety: ASIL_B :satisfied_by: comp__baselibs_containers_rust[version==1] - :belongs_to: comp__baselibs_containers_rust[version==1] :status: valid :version: 1 @@ -213,7 +200,6 @@ Non-Functional Requirements :security: NO :safety: ASIL_B :satisfied_by: comp__baselibs_containers_rust[version==1] - :belongs_to: comp__baselibs_containers_rust[version==1] :status: valid :version: 1 @@ -225,7 +211,6 @@ Non-Functional Requirements :security: NO :safety: ASIL_B :satisfied_by: comp__baselibs_containers_rust[version==1] - :belongs_to: comp__baselibs_containers_rust[version==1] :status: valid :version: 1 @@ -237,7 +222,6 @@ Non-Functional Requirements :security: NO :safety: ASIL_B :satisfied_by: comp__baselibs_containers_rust[version==1] - :belongs_to: comp__baselibs_containers_rust[version==1] :status: valid :version: 1 diff --git a/docs/baselibs/components/flatbuffers/docs/architecture/index.rst b/docs/baselibs/components/flatbuffers/docs/architecture/index.rst index f98e71e92d..b29d6e85a1 100644 --- a/docs/baselibs/components/flatbuffers/docs/architecture/index.rst +++ b/docs/baselibs/components/flatbuffers/docs/architecture/index.rst @@ -13,9 +13,120 @@ # ******************************************************************************* FlatBuffers Component Architecture -================================== +################################## -.. To be created. Link from comp_req to comp is mandatory for score metamodel check. +.. document:: FlatBuffers Architecture + :id: doc__flatbuffers_architecture + :status: valid + :version: 1 + :safety: ASIL_B + :security: NO + :realizes: wp__component_arch + +Overview +******** + +The component wraps the upstream Google FlatBuffers library. Code and binary buffers are generated from +``.fbs`` schemas via the bundled ``flatc`` Bazel rules. +Primary use case: loading module configuration, see :need:`doc__flatbuffers` for the full component description. + + +Requirements Linked to Component Architecture +********************************************* + +.. needtable:: Overview of Component Requirements + :style: table + :columns: title;id + :filter: search("comp__baselibs_flatbuffers", str(satisfied_by)) + :colwidths: 70,30 + +Description +*********** + +FlatBuffers provides three entry points — :need:`logic_arc_int_op__flatbuffers__loadbuffer`, +:need:`logic_arc_int_op__flatbuffers__versionreader`, and +:need:`logic_arc_int_op__flatbuffers__generatedcode` per supported language. +C++ and Rust are (targeting) ASIL-B implementations. Python follows the same three-entry-point architecture +as a supportive (QM) implementation, other languages may be added on demand. + +Design Decisions: +================= + +C++ Interface - Upstream Implementation Exposure +------------------------------------------------- + +.. dec_rec:: C++ Interface - Upstream Implementation Exposure + :id: dec_rec__flatbuffers__upstream_impl_exposure + :context: C++ interface - upstream flatbuffers types exposed to consumers + :decision: use flatc + :status: accepted + :version: 1 + +Use ``flatc`` for C++ code generation and the ``flatbufferscpp`` Bazel target as the +sanctioned C++ interface for FlatBuffers consumers, with direct upstream primitives discouraged. + +Context +^^^^^^^ +The component must expose FlatBuffers to C++ consumers in an ASIL-B-capable manner. +The ``flatc`` compiler generates builder, verifier, and accessor header code from ``.fbs`` schemas. +Generated code depends on runtime types (``flatbuffers::Table``, ``flatbuffers::Verifier``, +``flatbuffers::Vector<>``, etc.) from the upstream library, making that dependency unavoidable. + +Consequences +^^^^^^^^^^^^ +- ``flatbufferscpp`` is a mandatory, visible compile-time dependency for all generated-code consumers. +- The sanctioned usage path is: verify via ``VerifyXxxBuffer()``; access data via generated accessors, + ``GetRoot<>()``, and keyed table-vector methods such as ``LookupByKey()``; construct via ``FlatBufferBuilder`` + and ``CreateXxx()`` / ``XxxBuilder`` helpers. +- Bypassing generated helpers (``StartTable()``, ``AddElement()``, ``EndTable()``, custom + allocators) is discouraged — incorrect sequencing leads to invalid buffers or undefined behavior. + +Alternatives Considered +^^^^^^^^^^^^^^^^^^^^^^^ + +Custom flatc-like code generator +"""""""""""""""""""""""""""""""" +Develop a bespoke code generator that wraps FlatBuffers internals and exposes only a +project-internal API, hiding upstream ``flatbuffers::*`` types from consumers. + +Advantages: + +- Cleaner API boundary: Consumers not exposed to upstream types. +- Controlled surface: Only explicitly approved operations visible to integrators. + +Disadvantages: + +- Correctness risk: A custom generator introduces an untested translation layer between schema intent and generated code. +- Schema coverage uncertainty: The upstream schema language evolves, a custom generator may + silently mishandle schema constructs it does not support, producing incorrect or incomplete code + without any diagnostic. +- Loss of community support: ``flatc`` benefits from broad industrial adoption + and a community test suite that directly validates generated-code correctness. + +Justification for the Decision +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The ``flatc`` generator carries established qualification evidence through broad industrial +adoption and a comprehensive test suite that validates generated-code correctness. Treating +direct usage of upstream primitives as a documented discouraged pattern achieves equivalent API discipline +through process controls. + +Design Constraints: +=================== + +``Verify*`` functions validate structural well-formedness only — payload integrity is outside scope :need:`aou_req__flatbuffers__data_integrity`. +The same applies to file access control :need:`aou_req__flatbuffers__access_control`. + +Rationale Behind Architecture Decomposition +******************************************* + +The component is not split into sub-components. The three key interface entry points are: + +- :need:`logic_arc_int_op__flatbuffers__loadbuffer`: raw file I/O, decoupled from any FlatBuffers specifics +- :need:`logic_arc_int_op__flatbuffers__versionreader`: lightweight opt-in version check, without requiring the full application schema +- :need:`logic_arc_int_op__flatbuffers__generatedcode`: schema-typed access layer (reader, verifier, builder) + +Static Architecture +******************* .. comp:: FlatBuffers :id: comp__baselibs_flatbuffers @@ -23,4 +134,85 @@ FlatBuffers Component Architecture :safety: ASIL_B :status: valid :version: 1 + :implements: logic_arc_int__baselibs__flatbuffers[version==1] :belongs_to: feat__baselibs[version==1] + +.. comp_arc_sta:: FlatBuffers Static View + :id: comp_arc_sta__baselibs__flatbuffers + :security: YES + :safety: ASIL_B + :status: valid + :version: 1 + :belongs_to: comp__baselibs_flatbuffers + :fulfils: + comp_req__flatbuffers__serialization[version==1], + comp_req__flatbuffers__access[version==1], + comp_req__flatbuffers__verification[version==1], + comp_req__flatbuffers__buffer_identification[version==1], + comp_req__flatbuffers__version_check[version==1], + comp_req__flatbuffers__asil[version==1] + + .. needarch:: + :scale: 50 + :align: center + + {{ draw_component(need(), needs) }} + +Dynamic Architecture +******************** + +.. comp_arc_dyn:: FlatBuffers Dynamic View + :id: comp_arc_dyn__baselibs__flatbuffers + :security: YES + :safety: ASIL_B + :status: valid + :version: 1 + :belongs_to: comp__baselibs_flatbuffers + :fulfils: + comp_req__flatbuffers__serialization[version==1], + comp_req__flatbuffers__access[version==1], + comp_req__flatbuffers__verification[version==1], + comp_req__flatbuffers__buffer_identification[version==1], + comp_req__flatbuffers__version_check[version==1], + comp_req__flatbuffers__asil[version==1] + + Put here a sequence diagram + +Interfaces +********** + +.. logic_arc_int_op:: LoadBuffer + :id: logic_arc_int_op__flatbuffers__loadbuffer + :security: YES + :safety: ASIL_B + :status: valid + :version: 1 + :included_by: logic_arc_int__baselibs__flatbuffers[version==1] + + | C++: see source_code_link ``*.hpp`` + | Rust: not yet available + | Python (QM): not yet available + +.. logic_arc_int_op:: VersionReader + :id: logic_arc_int_op__flatbuffers__versionreader + :security: YES + :safety: ASIL_B + :status: valid + :version: 1 + :included_by: logic_arc_int__baselibs__flatbuffers[version==1] + + | C++: see source_code_link ``*.hpp`` + | Rust: not yet available + | Python (QM): not yet available + +.. logic_arc_int_op:: GeneratedCode + :id: logic_arc_int_op__flatbuffers__generatedcode + :security: YES + :safety: ASIL_B + :status: valid + :version: 1 + :included_by: logic_arc_int__baselibs__flatbuffers[version==1] + + | C++: see source_code_link starlark rule ``generate_cpp`` + | Rust: not yet available + | Python (QM): not yet available diff --git a/docs/baselibs/components/log_frontend/docs/requirements/index.rst b/docs/baselibs/components/log_frontend/docs/requirements/index.rst index c93691c7c4..a47a9aedaf 100644 --- a/docs/baselibs/components/log_frontend/docs/requirements/index.rst +++ b/docs/baselibs/components/log_frontend/docs/requirements/index.rst @@ -32,7 +32,6 @@ Requirements :security: NO :safety: ASIL_B :satisfied_by: comp__logging[version==1] - :belongs_to: comp__logging[version==1] :status: valid :version: 1 diff --git a/score/flatbuffers/bazel/BUILD b/score/flatbuffers/bazel/BUILD index 34da686c22..7c2fa467fe 100644 --- a/score/flatbuffers/bazel/BUILD +++ b/score/flatbuffers/bazel/BUILD @@ -22,3 +22,9 @@ py_binary( tags = ["manual"], visibility = ["//visibility:public"], ) + +filegroup( + name = "starlark_rule_links", + srcs = [":codegen.bzl"], + visibility = ["//visibility:public"], +) diff --git a/score/flatbuffers/bazel/codegen.bzl b/score/flatbuffers/bazel/codegen.bzl index 21a1154aee..5353c04bd3 100644 --- a/score/flatbuffers/bazel/codegen.bzl +++ b/score/flatbuffers/bazel/codegen.bzl @@ -136,6 +136,8 @@ generate_cpp = rule( doc = "Automatically included buffer_version.fbs for common buffer version support.", ), }, + + # req-Id: logic_arc_int_op__flatbuffers__generatedcode doc = """Generates a C++ header file from a FlatBuffer schema (.fbs) file. This rule uses the flatc compiler from the @flatbuffers repository with diff --git a/score/flatbuffers/i_version_reader.hpp b/score/flatbuffers/i_version_reader.hpp index 040e3353c3..46ab62b9a7 100644 --- a/score/flatbuffers/i_version_reader.hpp +++ b/score/flatbuffers/i_version_reader.hpp @@ -27,6 +27,7 @@ namespace score { namespace flatbuffers { +// # req-Id: logic_arc_int_op__flatbuffers__versionreader /// @brief Abstract interface for reading and verifying the version information /// embedded in a FlatBuffer that follows the common buffer diff --git a/score/flatbuffers/load_buffer.hpp b/score/flatbuffers/load_buffer.hpp index d4f9cbc851..f92efb81b2 100644 --- a/score/flatbuffers/load_buffer.hpp +++ b/score/flatbuffers/load_buffer.hpp @@ -29,6 +29,7 @@ namespace score namespace flatbuffers { +// # req-Id: logic_arc_int_op__flatbuffers__loadbuffer /// @brief Loads the entire contents of a binary file into a /// `std::vector`. diff --git a/score/flatbuffers/version_reader.hpp b/score/flatbuffers/version_reader.hpp index 6f83693df5..d3d1efeb41 100644 --- a/score/flatbuffers/version_reader.hpp +++ b/score/flatbuffers/version_reader.hpp @@ -20,6 +20,7 @@ namespace score { namespace flatbuffers { +// # req-Id: logic_arc_int_op__flatbuffers__versionreader /// @brief Default implementation of `IVersionReader`. ///