diff --git a/README.md b/README.md index ab374eb..10679d6 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,27 @@ # demo-epb — Elektrische Parkbremse -Vollstaendige Demo des [slohmaier Dev Process](https://gitea.slohmaier.com/slohmaier/dev-process) anhand einer EPB-Steuergeraet-Software. Zeigt ASPICE 4.0 / ISO 26262-konforme Entwicklung in einem Monorepo: Anforderungen, Architektur, Code, Tests, Reviews, MISRA — alles auf einen Pull-Request-Klick verifizierbar. +Vollständige Demo des [slohmaier Dev Process](https://gitea.slohmaier.com/slohmaier/dev-process) anhand einer EPB-Steuergerät-Software. Zeigt ASPICE 4.0 / ISO 26262-konforme Entwicklung im Monorepo: Anforderungen, Architektur, Code, Tests, Reviews, MISRA, Safety Case, Manuals — alles auf einen Pull-Request-Klick verifizierbar, alles in einem Release-Bundle. -> Diese Software ist **bewusst kein Produktivcode** — sie ist die Demonstration des Engineering-Verfahrens. Code-Umfang absichtlich klein, Prozess-Tiefe vollstaendig. +> Diese Software ist **bewusst kein Produktivcode** — sie ist die Demonstration des Engineering-Verfahrens. Code-Umfang bewusst klein, Prozess-Tiefe vollständig. ## Was die Demo zeigt -| Artefakt-Typ | Anzahl | Pfad | -|---------------------|--------|---------------------| -| Plaene (Word) | 5 | `docs/*.docx` | -| Audit-Artefakte (Word) | 3 | `docs/reviews/`, `docs/non-conformities/`, `misra/records/` | -| System-Anforderungen| 10 | `reqs/sys/` | -| Software-Anforderungen | 25 | `reqs/swe/` | -| System-Architektur | 5 | `arch/sys/` | -| Software-Architektur| 10 | `arch/swe/` | -| Implementierte Komponenten | 3 (1×ASIL-D, 1×ASIL-B, 1×QM) | `src/` | -| Stub-Komponenten | 7 | `src/stubs/` | -| Unit-Tests | 28 | `tests/unit/` | -| CI-Pipeline | 1 | `.gitea/workflows/` | +| Kategorie | Inhalt | +|-----------|--------| +| **Pläne** (Word) | 5 (PID, PM-, QA-, SWE-, Test-Plan) | +| **Safety-Doku** (Word) | 6 (HARA, Safety Case, FMEDA, MISRA-Compliance, Verification-Report, Tool-Qualification) | +| **Manuals** (Word) | 2 (User-Manual, Service-Manual) | +| **Audit-Artefakte** (Word) | 3 (Review-Protokoll, Non-Conformity, MISRA-Deviation-Record) | +| **System-Anforderungen** | 10 in `reqs/sys/` (Markdown + Doorstop-Style) | +| **Software-Anforderungen** | 25 in `reqs/swe/` | +| **System-Architektur** | 5 in `arch/sys/` mit PlantUML | +| **Software-Architektur** | 10 in `arch/swe/` mit PlantUML | +| **Implementierte C-Komponenten** | 4 (Apply Ctrl D, Safety Mgr D, Actuator Drv B, Switch Db QM) | +| **Stub-Komponenten** | 6 weitere (Header only) | +| **Unit-Tests** | 41, alle grün | +| **CI-Workflows** | 2 (validate + release) | +| **CI-Artefakte** | Coverage HTML, Traceability Matrix, Diagramme SVG, Doxygen, Test-Report, Cppcheck-XML | +| **Cross-Platform-Runner** | Linux + macOS + Windows | ## Quick Start @@ -25,39 +29,67 @@ Vollstaendige Demo des [slohmaier Dev Process](https://gitea.slohmaier.com/slohm git clone https://gitea.slohmaier.com/slohmaier/demo-epb.git cd demo-epb -# Build + Tests -make test +# Tests +make test # 41 Tests, alle grün -# Mit Coverage (benoetigt lcov) +# Mit Coverage (braucht lcov) make coverage open build/coverage-html/index.html -# Statische Analyse + MISRA (benoetigt cppcheck) +# Test-Summary-Report (HTML) +make test-report +open build/test-report.html + +# Statische Analyse + MISRA (braucht cppcheck) make static make misra + +# API-Doku (braucht doxygen) +make docs +open build/api-doc/html/index.html + +# Traceability-Matrix (HTML) +python3 tools/traceability.py publish docs/traceability +open docs/traceability/index.html + +# PlantUML-Diagramme rendern (SVG) +python3 tools/render_plantuml.py ``` -## Gefuehrte Tour (~30 min) +## Geführte Tour (~30 min) -### 1. Projektplanung -Start in `docs/`: +### 1. Projektplanung (Word) +`docs/`: - **PID.docx** — Was wird gebaut und warum -- **SWE-Plan.docx** — Wie wird gebaut: Sprache, Standards, Branching, Review-Regeln, Coverage-Ziele pro ASIL -- **QA-Plan.docx** — Qualitaetsmassnahmen, Reviews, NC-Management +- **SWE-Plan.docx** — Sprache, Standards, Branching, Reviews, Coverage-Ziele +- **QA-Plan.docx** — Qualitätsmaßnahmen, Reviews, NC-Management - **PM-Plan.docx**, **Test-Plan.docx** — Arbeitspakete + Teststrategie -### 2. Sicherheits-Logik (das ASIL-D Stueck) -`reqs/sys/SYS-001.md` → `arch/swe/SWA-002.md` → `src/apply_controller.c` → `tests/unit/test_apply_controller.c` +### 2. Funktionale Sicherheit (Word — `docs/safety/`) +- **HARA.docx** — Hazard Analysis & Risk Assessment. Leitet **ASIL-D** ab. +- **Safety-Case.docx** — Argumentation in GSN-Style, warum die Sicherheitsziele erfüllt sind +- **FMEDA.docx** — Pro-Komponente Failure Modes mit Diagnostic Coverage +- **Tool-Qualification-Cppcheck.docx** — Tool-Qual für Cppcheck (TI2/TD2/TCL2) +- **MISRA-Compliance-Statement.docx** — formaler Compliance-Nachweis +- **Verification-Report.docx** — V-Modell rechte Seite zusammenfassend -Das ist die Traceability-Kette: System-Sicherheitsziel → Software-Architektur → Code → Test. +### 3. Manuals (Word — `docs/manuals/`) +- **User-Manual.docx** — Fahrerhandbuch-Auszug (Apply, Release, Hill-Hold, LED-Codes) +- **Service-Manual.docx** — Werkstatt-Doku mit UDS-DTCs, Service-Modus, Sensor-Prüfung -### 3. Anforderungen + Architektur (Doorstop in Markdown) -- `reqs/sys/` und `reqs/swe/` — alle Anforderungen mit Mapping -- `arch/sys/` und `arch/swe/` — Architektur mit Mapping per `links:` im Frontmatter -- Eingebettete PlantUML-Diagramme rendern direkt in Gitea +### 4. Sicherheits-Logik (das ASIL-D Stück) +Traceability-Kette: +``` +reqs/sys/SYS-001.md → arch/swe/SWA-002.md → src/apply_controller.c → tests/unit/test_apply_controller.c +``` -### 4. Code mit Mapping-Tags -Jede `.c`-Datei traegt `@arch`, `@reqs` im Header: +### 5. Anforderungen + Architektur (Doorstop in Markdown) +- `reqs/sys/` + `reqs/swe/` — Anforderungen mit Mapping +- `arch/sys/` + `arch/swe/` — Architektur mit Mapping per `links:` im Frontmatter +- Eingebettete PlantUML-Diagramme rendern direkt in Gitea (UI) und als SVG im Release-Bundle + +### 6. Code mit Mapping-Tags +Jede `.c`-Datei trägt `@arch`, `@reqs`, `@asil` im Header: ```c /** @@ -69,76 +101,73 @@ Jede `.c`-Datei traegt `@arch`, `@reqs` im Header: */ ``` -So ist Code -> Architektur -> Anforderung auf einen `grep` durchsuchbar. +### 7. Tests mit Anforderungs-Tags +`tests/unit/test_*.c` referenziert die Requirements per `@reqs`. Test-Report (`build/test-report.html`) macht das Mapping klickbar sichtbar. -### 5. Tests mit Anforderungs-Tags -`tests/unit/test_apply_controller.c` referenziert die Requirements per `@reqs`. CI mit Coverage-Report belegt, dass jede Anforderung getestet ist. +### 8. Audit-Artefakte +- `docs/reviews/REV-001.docx` — Review-Protokoll für die ASIL-D-Komponente +- `docs/non-conformities/NC-001.docx` — NC mit Korrekturmaßnahme +- `misra/records/MISRA-REC-001.docx` — MISRA Advisory-Deviation -### 6. Audit-Artefakte -- `docs/reviews/REV-001.docx` — Review-Protokoll fuer die ASIL-D-Komponente -- `docs/non-conformities/NC-001.docx` — Beispiel einer Non-Conformity mit Korrekturmassnahme -- `misra/records/MISRA-REC-001.docx` — MISRA Deviation Record fuer eine bewusste Advisory-Abweichung +### 9. CI-Pipeline (`.gitea/workflows/validate.yml`) +Bei jedem Push: +1. **Cross-Platform Build + Test** auf Linux + macOS + Windows +2. **Static Analysis** (Cppcheck) +3. **MISRA-Check** (Cppcheck + MISRA-Addon) +4. **Coverage** (gcov/lcov) +5. **Traceability-Check** (bidirektional) +6. **PlantUML-Render** (alle Diagramme als SVG) +7. **Doxygen-API-Doc** +8. **Test-Summary-Report** -### 7. CI-Pipeline -`.gitea/workflows/validate.yml` — bei jedem Push laeuft: -1. Cppcheck (Static Analysis) -2. Cppcheck + MISRA-Addon -3. Build + Unit Tests -4. Coverage (gcov/lcov) -5. Doorstop-Traceability-Check +Alles als Gitea-Artefakte abrufbar. -## Architektur-Ueberblick +### 10. Release-Workflow (`.gitea/workflows/release.yml`) +Auf Tag-Push `v*.*.*`: +- Vollständigen Build + alle Reports +- Bündelt **Source-Archive + Artefakt-Archive** (CI-Output + alle Word-Docs) +- Erzeugt Gitea-Release mit Release-Notes + +Beispiel: https://gitea.slohmaier.com/slohmaier/demo-epb/releases + +## Architektur-Überblick ``` - +----------------------+ - | EPB ECU (SA-001) | - | +-----------------+ | - | | Safety Mgr (D) | | - | +-----------------+ | - | | Apply Ctrl (D) | | - | +-----------------+ | - | | Actuator Drv (B)| | - | +-----------------+ | - | | Wheel Speed (B) | | - | | Inclino (B) | | - | +-----------------+ | - | | Switch DB (QM) | | - | | Display (QM) | | - | | Diag (QM) | | - | | Service (QM) | | - | | Logger (QM) | | - | +-----------------+ | - +----------------------+ - | | - Aktor L Aktor R - (SA-002) (SA-002) + EPB ECU (SA-001) + +----------------------------------+ + | Safety Manager (D) | ← arch/swe/SWA-001.md + | Apply Controller (D) | ← arch/swe/SWA-002.md + | Actuator Driver (B) | ← arch/swe/SWA-003.md + | Wheel Speed Plausi (B) [stub] | + | Inclino Filter (B) [stub] | + | Switch Debouncer (QM) | ← arch/swe/SWA-006.md + | Display Manager (QM) [stub] | + | Diag Manager (QM) [stub] | + | Service Mode (QM) [stub] | + | Logger (QM) [stub] | + +----------------------------------+ + | | + Aktor L (SA-002) Aktor R (SA-002) ``` ## Format-Strategie -| Inhalt | Format | Begruendung | -|---------------------|-------------------|-------------------------------------------------| -| Plaene + Audit-Doku | **Word** (.docx) | Industriestandard fuer ISO-9001-Freigabe | -| Requirements + Arch | **Markdown** (Doorstop) | Lebendig, diff-bar, Traceability per Skript | -| Code, Tests, CI | C / YAML | klar | +| Inhalt | Format | Begründung | +|--------|--------|------------| +| Pläne + Safety + Audit + Manuals | **Word** (.docx) | Industriestandard für ISO-9001-Freigabe | +| Requirements + Architektur | **Markdown** (Doorstop-Stil) | Lebendig, diff-bar, Traceability per Skript | +| Code, Tests, CI | C / YAML | klar | +| Release-Bundle | tar.gz mit allem | Eine Datei für den Auditor | -Beide Welten gehen ueber `tools/`-Skripte ineinander ueber: Markdown ist Source of Truth, Word wird per pandoc daraus gebaut. - -## Generatoren - -| Skript | Zweck | -|---------------------------------------|----------------------------------------------------| -| `tools/generate_doorstop_items.py` | Erzeugt alle 50 Requirements + Arch-Elemente aus Strukturdaten | +Markdown ist Source of Truth, Word wird per pandoc daraus gebaut. ## Referenzen -- [slohmaier/dev-process](https://gitea.slohmaier.com/slohmaier/dev-process) — die Methodik +- [slohmaier/dev-process](https://gitea.slohmaier.com/slohmaier/dev-process) — Methodik-Repo - ASPICE 4.0 -- ISO 26262 (insbesondere Part 6 — Software) +- ISO 26262 (insbesondere Part 2, 3, 5, 6, 8, 10) - MISRA C:2012 ## Lizenz MIT — siehe [LICENSE](LICENSE). - -