Last refreshed: 2026-08-22 (test inventory and execution evidence refresh).

Status: First draft, 2026-05-02. Populated during Phase 7 of docs/QUALIFICATION_ROADMAP.md. Subject to revision after the first external assessor review.

DO-178C reference: Section 11.4 (SCMP content) and Section 7 (Configuration Management Process). IEC 61508-3 reference: Clause 6.2.3 (Configuration management). ISO 26262-8 reference: Clause 7 (Configuration management).

Owner: Brighton Sikarskie (single developer / maintainer).

1. Configuration items

The configuration item set is the union of everything tracked in this git repository, plus the pinned versions of pre-existing software listed in docs/SOUP/. The repository root is the single source of truth.

1.1 First-party source code

Path	Description
libs/ra8_secure_app/	Ring 5 secure-side substrate (key vault, secure-only logic).
libs/ra8_core/	ra8_err, ra8_check, ra8_log, ra8_assert, helpers.
libs/ra8_hal/	Peripheral drivers and register header files.
libs/ra8_nsc/	TrustZone non-secure-callable veneers.
libs/ra8_*_pal/	Platform abstraction layers (ra8_net_pal, ra8_usb_pal, ...).
libs/ra8_psa_crypto/	PSA Crypto integration shim.
libs/ra8_modem_at/	AT-command modem stack.
libs/ra8_power_profile/	Power-profile management.
libs/ra8_ota/	OTA orchestration (Phase 5).
apps/shared_libs/	Reusable application-domain libraries shared by product forms.
apps/host/, apps/board/	Hosted and firmware product compositions.
examples/ek_ra8d2/**/<app>/	Classified RA8D2 applications selected by scripts/dev/ra8_apps.py.
examples/ra8p1_foundation/<app>/	RA8P1 foundation applications selected by scripts/dev/ra8_apps.py.
examples/_unsupported/	Shelved applications excluded from the selected inventory.
port/	First-party target, middleware, and host adaptation layers.
tools/	First-party build, inspection, packaging, and emulation tools.
tests/	Repository-level host test harness and test support.
scripts/	First-party build, verification, CI, HIL, and developer automation.

1.2 Per-application boot code

Each application directory owns examples/ek_ra8d2/<tier>/.../<app>/src/main.c and a root CMakeLists.txt. The selected board layer supplies canonical boot and linker artifacts; an application keeps a local file only when it intentionally overrides that default:

examples/ek_ra8d2/<tier>/.../<app>/src/main.c
examples/ek_ra8d2/<tier>/.../<app>/inc/ for app-local interfaces
CMakeLists.txt
hil.conf where the app participates in HIL
optional app-local overrides under examples/ek_ra8d2/<tier>/.../<app>/src/: vector_table.c, system_init.c, secure_exception.c, nmi_exception.c, and trustzone_init.c – the exact set ra8_add_app() honours
optional examples/ek_ra8d2/<tier>/.../<app>/inc/trustzone_init.h and root-level examples/ek_ra8d2/<tier>/.../<app>/linker_script.ld

Product forms follow the same ownership rule; for example, the e-reader's exception override is apps/board/stand_alone/ereader/src/secure_exception.c.

The canonical EK-RA8D2 defaults are under libs/ra8_board_ek_ra8d2/{src/boot,ld}/; RA8P1 uses the corresponding libs/ra8_board_ra8p1/ layer.

1.3 Build configuration

Path	Description
CMakeLists.txt (root)	Top-level orchestrator; auto-discovers example apps.
justfile (root)	Authoritative task interface; includes the namespaced modules under just/.
cmake/toolchain-ra8d2.cmake	arm-none-eabi cross-compile settings.
cmake/ra8_warnings.cmake	Warning + stack-usage gate (-Wstack-usage=2048 default).
Doxyfile	Doxygen configuration (docs site + warning gate).

1.4 Test configuration items

Path	Description
tests/CMakeLists.txt	Host test build configuration; gates MC/DC instrumentation.
tests/build_tests.sh	Host-test build entry point.
tests/run_tests.sh	Host-test execution entry point (ctest).
Distributed test sources	Dated 2026-08-22 snapshot: 693 files (689 C, 4 C++), 689 registrations on clean standalone macOS and Linux, and 689/689 passing in the Linux/devcontainer gate in 8.66 s. This is retained historical evidence, not the current-tree census; macOS execution was not claimed.

1.5 Verification + audit scripts

Path	Description
scripts/report/mcdc_report.sh	MC/DC measurement and gate.
scripts/checks/misra_check_inner.sh	MISRA-C 2012 advisory audit.
scripts/checks/stack_usage_check.py	Stack-bound aggregator.
scripts/checks/cite_check.py	HUM citation validator.
scripts/checks/check_world_tags.py	TrustZone world-tag enforcement.
scripts/checks/check_obsolete_standards.py	Rejects superseded safety-standard references.
scripts/checks/check_no_dynamic_alloc.py	NASA P10 Rule 3 enforcement.
scripts/checks/check_mcdc_block.py	@par MC/DC: block enforcement on tests.
scripts/checks/check-since-version.py	Doxygen @since enforcement.
scripts/checks/check-copyright.py	Copyright + SPDX header enforcement.
scripts/report/roadmap_stats.py	../ROADMAP.md summary block freshness gate.
scripts/report/tree_coverage.sh	gcovr whole-tree coverage measurement.
scripts/checks/format_code.sh	clang-format wrapper.
scripts/checks/clang_tidy.sh	clang-tidy wrapper.
scripts/dev/flash.sh	J-Link flash wrapper (HW operations).
scripts/git/pre-commit	Pre-commit hook (the authoritative gate suite).

1.6 Documentation

Path	Description
CLAUDE.md	Coding rules; informs both human and AI contributors.
docs/STYLE_GUIDE.md	Authoritative human-facing style guide.
docs/RING_AND_WORLD.md	Architectural-ring and TrustZone-world tagging system.
docs/MEMORY_MAP.md	Linker memory map.
docs/MCDC.md, docs/MCDC_GAPS.md	MC/DC infrastructure and gap list.
docs/MISRA.md, .github/misra-baseline.txt	MISRA-C 2012 audit policy and baseline.
docs/STACK_USAGE.md	Stack-bound analysis.
docs/HARDWARE_BRINGUP.md	EVM bring-up + smoke procedure.
docs/QUALIFICATION_ROADMAP.md	Phase plan to SIL 3 / DAL B.
docs/qualification/	All planning + verification + accomplishment documents.
docs/SOUP/	Per-component pre-existing-software qualification basis.
docs/reference/	Renesas datasheets and HUM (committed PDFs).

1.7 Vendor SOUP (frozen in tree)

The two canonical vendor roots hold the pinned source of every SOUP component listed in docs/SOUP/README.md: platform-wide dependencies live under libs/third_party/, while dependencies used only by application products and their companion host tools live under apps/shared_libs/third_party/. Each component is vendored at the exact version recorded in its docs/SOUP/<name>.md file. Updates require:

A bump of the component directory under its existing canonical vendor root to the new upstream tag.
A diff review against the previous vendored version.
An update of docs/SOUP/<name>.md (version, last-review date, any new advisories considered).

1.8 CI configuration

Path	Description
.github/workflows/firmware.yml	Primary CI workflow (build, test, MC/DC, coverage, lint).
.github/mcdc-baseline.txt	Pinned MC/DC baseline (regression gate).
.clang-format	Formatter configuration.
.clang-tidy	Linter configuration (NASA P10 Rule 4 thresholds).
.clangd	Editor integration; strips ARM-only flags.
.cppcheck-suppressions	MISRA deviation justifications inline.
.editorconfig, .gitattributes, .gitignore	Repository hygiene.

2. Configuration management activities

2.1 Version-control system

Tool: Git.
Authoritative remote: GitHub repository ra8-firmware under user account bsikar (origin).
Working copy: a Git linked worktree created through just workspace::new; no host-specific absolute path is configuration authority.

2.2 Branching model

Long-lived branches: dev is the working integration branch and main is the release branch.
Feature work occurs on short-lived issue branches and worktrees, then lands on dev after its required gates pass. Release promotion from dev to main uses a pull request.
No release branches today; tags will be added when the first release lands (see Section 5).

2.3 Commit policy

Semantic commit prefix per docs/STYLE_GUIDE.md (e.g. tests:, libs:, secure_app+tests:, revert:).
Commits are small and self-contained; one logical change per commit. Recent examples on main:
- 8981092f0 secure_app+tests: properly order key_import enums; wire ra8_psa_crypto
- 6cb7f02c7 libs: ra8_modem_at, ra8_power_profile, ra8_sensor_bme280 + unit tests
- 10b9eedfc ota: Phase-5 OTA orchestration + secure-side commit veneers
Commit messages contain no AI attribution. This is a hard project rule per CLAUDE.md.
Force-push to dev or main is forbidden.
Force-push to topic branches before merge is permitted.

2.4 Pre-commit gate (authoritative configuration of "what cannot land")

The hook at scripts/git/pre-commit enforces the following gates on every commit. Failure of any gate refuses the commit:

ASCII-only source files (fix-encoding.py --check).
C23 patterns: no _Static_assert, no = {0}, no #include <stdbool.h>.
Defensive-paren on numeric #define values.
clang-format (no diff).
clang-tidy (no warnings).
cppcheck warning/style/performance/portability (production files only).
Doxygen @since tag enforcement on public headers.
Copyright + SPDX header enforcement.
HUM citation validator (cite_check.py --strict).
World-tag validator (check_world_tags.py --strict).
ROADMAP summary freshness (roadmap_stats.py --check, strict).
Obsolete-standards reference scan (rejects superseded safety-standard references, strict).
@par MC/DC: block on staged tests (check_mcdc_block.py).

The hook is mirrored by CI; it is the developer's responsibility not to bypass the local installation.

2.5 CI gate (authoritative configuration of "what cannot merge")

.github/workflows/firmware.yml mirrors the pre-commit suite and adds the heavier gates that are too slow for per-commit:

ASCII, copyright, @since tag scanners (mirrors of pre-commit).
clang-format, clang-tidy.
Host unit tests (unit-tests job).
Coverage gate (just quality::gate::run coverage-tree).
MC/DC coverage gate against .github/mcdc-baseline.txt (mcdc job).
pre-commit-checks job (full mirror of the pre-commit hook).
Cross-build matrix over every example app (build-cross job).
Doxygen warning gate (docs job).
cppcheck full-tree run (cppcheck job).
PR-only MC/DC delta comment (coverage-comment job).

A PR cannot be merged with any CI gate red. This is the binding configuration-control point.

3. Problem reporting

3.1 Reporting channel

GitHub Issues on the ra8-firmware repository are the authoritative problem-report log. There is no separate bug tracker.

3.2 Severity classification

Per docs/QUALIFICATION_ROADMAP.md planning vocabulary, the project uses the following severity tiers:

Severity	Meaning
crit	Defect that violates a SIL 3 / Level B safety claim or breaks main.
high	Defect on the critical-path module set (ISR, MPU, XSPI, USB, SCI, PSA).
med	Defect in any first-party module not on the critical path.
low	Cosmetic, documentation, or style defect.

3.3 Linkage convention

Every PR that closes an issue uses Fixes #N in the PR body.
Every commit that addresses an issue references it as (#N) in the subject line.
A defect that surfaces a missing test must be paired with a new category- or module-local test entry in the same PR.

3.4 Audit trail

The combined git log + GitHub Issues + PR review history form the complete defect-resolution audit trail. No additional tracker is required for the qualification claim.

4. Change control

4.1 Inbound change procedure

Working changes land on dev; release promotion to main arrives via a pull request.
The pre-commit hook enforces the per-commit gates; CI enforces the per-PR gates (Section 2.5).
A PR may not be merged with any CI gate red.
The CLAUDE.md zero-backward-compatibility policy means that breaking changes are explicit: API renames, deletions, and type changes update every call site in the same commit. There is no deprecation window.

4.2 Baselining

A "baseline" in this project is a git commit hash. A CI-green dev commit is the working baseline; release baselines live on main. External references (the SVR, the SAS, the SOUP review records) cite commits by their abbreviated SHA. Signed tags will identify released baselines after the first release lands (Section 5).

4.3 Configuration of build environment

The cross-compiler is pinned to Arm GNU Toolchain 13.3.rel1 (gcc 13.3.1) and enforced by cmake/toolchain-ra8d2.cmake (a -dumpfullversion 13.3 assertion, FATAL by default) – not the Ubuntu apt gcc-arm-none-eabi. The host verification tools (clang-18/llvm-18, cppcheck, clang-format-22, clang-tidy, doxygen, graphviz) run from the pinned devcontainer image.
The devcontainer image (.devcontainer/Dockerfile) is checked in and pins the base image by digest, exact versions where supported, and versioned major-package contracts for the LLVM/GCC families, so a developer-local just ci reproduces CI. CI remains the authoritative environment. See docs/TOOLCHAIN.md.

4.4 SOUP change control

Any update to a vendored library under libs/third_party/ or apps/shared_libs/third_party/ requires:

An updated docs/SOUP/<name>.md (version, last-review date, reviewed advisories).
A diff review against the previous vendored version.
PR-level approval; gate as for any other change.

5. Configuration status accounting

5.1 Status records

git log is the authoritative change history.
git tag is the authoritative release register. No release tags exist today. The first signed tag will be cut at the end of roadmap Phase 7.
CI run history (GitHub Actions) is the authoritative build-and-verification record.

5.2 Release tagging procedure (for future use)

When a release is cut, the procedure is:

Update CHANGELOG.md with the release scope.
Run just quality::local::mcdc, just quality::local::misra, just quality::local::stack_usage, just quality::local::test, just hil::run and archive the reports under docs/qualification/release/<tag>/.
Tag the release: git tag -s vX.Y.Z -m "Release X.Y.Z".
Push the tag: git push origin vX.Y.Z.
Update docs/qualification/SAS.md to cite the new tag.

The signing key fingerprint and key-management procedure will be documented at the time of the first signed release.

5.3 Reporting cadence

Per-PR: CI logs (automatic, persisted by GitHub).
Per quarter: re-run just quality::local::gate misra, review the ratcheted .github/misra-baseline.txt, and re-stamp docs/MISRA.md audit table.
Per quarter: re-run just quality::local::mcdc, refresh docs/MCDC_GAPS.md, re-stamp docs/MCDC.md measurement-history table.
Per release: full audit-pack regeneration (Section 5.2).

6. Archive, retrieval, and release

6.1 Archive

Primary record: this git repository (the GitHub remote is the authoritative copy).
Vendored SOUP source: both libs/third_party/ and apps/shared_libs/third_party/ are checked into the same repository so that a single git clone retrieves the full build configuration. There is no external dependency fetch at build time.
CI artifacts: coverage-html and mcdc-report archives uploaded per CI run with 14-day retention (per .github/workflows/firmware.yml). For qualification claims, CI artifacts will be re-archived under docs/qualification/release/<tag>/ at release time.
Reference manuals: Renesas datasheets and HUM committed under docs/reference/ so they are always retrievable from the same archive.

6.2 Retrieval

A bit-exact rebuild of any historical state is achieved by:

git clone <remote> the repository.
git checkout <commit-or-tag>.
Reproduce the CI environment through the Ansible-provisioned runner or the digest-pinned .devcontainer/Dockerfile; Python dependencies resolve from pyproject.toml and uv.lock.
just apps::build <app> to cross-build, or just quality::local::test to host-test.

6.3 Retention

git log retained indefinitely (this is the primary record).
CI logs retained per GitHub Actions defaults (90 days for logs; 14 days for the explicitly-configured artifact uploads).
Long-term audit-pack retention is via the docs/qualification/ release/<tag>/ snapshot taken at release time.

7. Software load control

7.1 Build outputs

The cross-build emits per-app ELF, HEX, and BIN files under build/<app>/.
The hex file is the authoritative production binary.
The build records the toolchain version (printed by the CI step Print toolchain version) and the source SHA in the build log.

7.2 Flash procedure

Tool: JLinkExe invoked via scripts/dev/flash.sh <hex-path>.
Probe: on-board J-Link OB (.env JLINK_SN) on the EK-RA8D2.
Verification: the J-Link verify command is the post-flash readback. A flash run that fails verify is treated as a load failure.

7.3 Hash recording

For each release-tagged build, the hex file SHA-256 is recorded in the release notes and in docs/qualification/release/<tag>/ hashes.txt.
For PR builds, the hex hash is captured in the CI log of the build-cross job. CI log retention bounds the audit window.

7.4 Load control on production hardware

There is no production fleet today; all loads are developer-bench loads against the EK-RA8D2 evaluation kit. When a production fleet is established the load-control procedure will be extended with a signed-update path (the OTA orchestration in libs/ra8_ota/ is the foundation).

8. Software life cycle environment control

8.1 Toolchain pinning

The CI workflow .github/workflows/firmware.yml, the checked-in .devcontainer/Dockerfile, and the canonical helpers under scripts/ci/ control the toolchain. The managed set includes:

gcc-arm-none-eabi, libnewlib-arm-none-eabi (cross compiler).
clang-18, llvm-18, libclang-rt-18-dev (host MC/DC chain).
clang-format, clang-tidy (style + lint).
cppcheck (static + MISRA).
cmake, ninja-build, gcc (build orchestration).
doxygen, graphviz (docs gate).
gcovr (coverage gate, synchronized from pyproject.toml and uv.lock).

Any toolchain bump updates its authoritative pin and follows the same PR + CI gating as a code change.

8.2 Devcontainer

The checked-in .devcontainer/ definition supplies the pinned development environment. Image construction and writable-worktree execution go through the canonical helpers in scripts/ci/, which also enforce the image identity used by the Just devcontainer recipes.

8.3 Operating-system + runner control

Normal CI runners: Ansible-managed, self-hosted ra8-ci listeners declared by infra/fleet.yml. The isolated fork-PR feedback lane is the only ubuntu-latest path and cannot reach self-hosted infrastructure. Runner changes are reviewed through the workflow schedules, Ansible roles, and the runner-image dependency gate.
HW-in-the-loop runner: dedicated native dev-box listener with an isolated SSH identity to the Raspberry Pi 5 rig. HIL-relevant pushes and trusted same-repository PRs schedule through .github/workflows/hil.yml; fork PRs are excluded and local selected-app runs remain available to HIL-equipped developers (docs/HIL_DEVELOPER_WORKFLOW.md).

9. References

CLAUDE.md – coding standard, character-encoding policy, no-AI-attribution policy, zero-backward-compatibility policy.
docs/QUALIFICATION_ROADMAP.md – phase plan and gap analysis.
docs/SOUP/ – pre-existing software register.
scripts/git/pre-commit – authoritative pre-commit gate suite.
.github/workflows/firmware.yml – authoritative CI gate suite.
IEC 61508-3:2010 Clause 6.2.3.
RTCA DO-178C:2011 Sections 7 and 11.4.
ISO 26262-8:2018 Clause 7.