1.4. Traceability¶
Traceability in software development refers to the ability to link various artifacts and components of a software project throughout its lifecycle. This includes requirements, architecture, design documents, code and tests.
In this project, traceability is achieved through the use of sphinx-needs tools.
1.4.1. Traceability Conventions¶
1.4.1.1. Types¶
Need Type |
Description |
ID Pattern |
|---|---|---|
req |
Software Requirement |
|
arch |
Software Architecture |
|
impl |
Implementation |
|
dimpl |
Detailed Design & Implementation |
|
dsgn |
Detailed Design |
|
test |
Unit Test |
|
itest |
Integration Test |
|
Short description must only contain letters, numbers, and hyphens.
Generally speaking every requirement should be traced through architecture, design, implementation and tests. The design and implementation can be combined if desired. In trivial cases, it is acceptable to skip architecture and/or design.
Rationale
Combining design and implementation reduces overhead, and is acceptable when the design is straightforward, and it’s easier to show the design in code comments than in separate documents.
1.4.1.2. Properties¶
This section documents the metadata properties used on sphinx-needs items to support Automotive SPICE (ASPICE) process compliance. These properties enable consistent classification, maturity tracking, and review workflows across all documentation artifacts.
1.4.1.2.1. Status¶
The :status: option tracks the maturity of each documentation item through its lifecycle.
It applies to all need types (req, arch, dsgn, impl, dimpl, test, itest).
Status |
Description |
Applies To |
|---|---|---|
|
Item is being written or is incomplete. Content may change significantly. This is the default status for newly created items. |
All need types |
|
Item has been reviewed and is considered correct and complete. Content accurately reflects the intended behavior or design. |
All need types |
|
Item has been formally approved by a reviewer or stakeholder. Content is frozen and may only change through a formal change request. |
All need types |
|
Item has been reviewed and rejected. The item needs rework before it can be accepted. |
All need types |
|
Item is no longer applicable. It is retained for historical reference but should not be relied upon. |
All need types |
Items without an explicit :status: should be treated as draft.
1.4.1.2.2. Lifecycle¶
The typical status progression for an item is:
draft --> valid --> approved
Items may transition to rejected from draft or valid during review.
Items may transition to obsolete from any status when they are superseded or no longer needed.
Usage Example
.. req:: Example Requirement
:id: req~example
:status: draft
The system must do something.
1.4.1.3. Requirement Type¶
The :type: option classifies requirements by their nature. This is primarily relevant
for req needs, but may optionally be applied to arch and dsgn items for
additional classification.
Type |
Description |
|---|---|
|
Describes a behavior or capability the system must provide. Functional requirements define what the system does in response to inputs or conditions. |
|
Describes a quality attribute such as performance, reliability, availability, security, or maintainability. Non-functional requirements define how well the system performs. |
|
Describes an external interface or API contract. Interface requirements define the boundaries and communication protocols between the system and external entities. |
|
Describes a design or implementation constraint imposed by the environment, standards, or organizational policies. Constraints limit the solution space without describing system behavior. |
Usage Example
.. req:: HTTP-Server
:id: req~sovd-api-http-server
:status: valid
:type: functional
The CDA must provide an HTTP- or HTTPS-server.
1.4.1.3.1. Code¶
Code can be added to the traceability by utilizing sphinx-codelinks. The short format in a comment is as follows:
[[ <ID of the need>, <title>, <type>, <links> ]]
One-Line Example:
/// [[ dimpl~sovd.api.https.certificates, Handle HTTPS Certificates, dimpl, test~sovd.api.https.certificates ]]
/// description of the function
fn test {
...
}
Note
type and links are optional, if left empty, type will be dimpl
multi-line definitions are not supported at the time of writing by the src-trace directive.
1.4.1.4. Overviews¶
Software Requirements
ID |
Title |
Status |
|---|---|---|
Alive Check |
draft |
|
DoIP Communication Parameters |
draft |
|
DoIP Connection Management |
draft |
|
Diagnostic Message Exchange |
draft |
|
DoIP Error Handling |
draft |
|
DoIP Message Framing |
draft |
|
DoIP Protocol Version Support |
draft |
|
Routing Activation |
draft |
|
DoIP TLS Communication |
draft |
|
Spontaneous VAM Handling Mode |
draft |
|
Vehicle Identification |
draft |
|
Database Loading |
draft |
|
Communication Initialization Mode |
draft |
|
DoIP Gateway Initialization |
draft |
|
ECU Discovery |
draft |
|
ECU List Persistence |
draft |
|
ECU List Persistence - Shutdown Update |
draft |
|
ECU States |
draft |
|
Startup Error Handling |
draft |
|
Startup Sequence |
draft |
|
Variant Detection |
draft |
|
Diagnostic Database Update Plugin |
draft |
|
Diagnostic Database Update Plugin - Authentication |
draft |
|
Diagnostic Database Update Plugin - Downgrade Protection |
draft |
|
Diagnostic Database Update Plugin - Safety |
draft |
|
Diagnostic Database Update Plugin - Verification |
draft |
|
DLT Logging |
draft |
|
DLT Logging - Context Identification |
draft |
|
DLT Logging - Compile-Time Feature Gate |
draft |
|
DLT Logging - Log Level Mapping |
draft |
|
DLT Logging - Runtime Configuration |
draft |
|
Vehicle Topology Plugin |
draft |
|
Vehicle Topology Plugin - Reset |
draft |
|
Vehicle Topology Plugin - Reset with Persisted List Control |
draft |
|
Data Type A_BYTEFIELD as Hex |
draft |
|
Communication Parameters API |
draft |
|
Component SDG/SDs |
draft |
|
Components Entity Collection |
draft |
|
Entity Data Types |
draft |
|
Explicit ECU Variant Detection |
draft |
|
Faults Endpoint |
draft |
|
Flash API |
draft |
|
Flash API - Data Source Restriction |
draft |
|
Functional Communication |
draft |
|
Health Monitoring Endpoint |
draft |
|
HTTP-Server |
draft |
|
HTTP-Server-Port |
draft |
|
HTTPS-Server configuration |
draft |
|
Lock Acquisition Policy |
draft |
|
Lock API |
draft |
|
Defunct Lock State |
draft |
|
HTTP 409 for Preempted Clients |
draft |
|
ECU Lock Endpoint Enforcement |
draft |
|
Lock Exclusivity |
draft |
|
Lock Exclusivity Policy |
draft |
|
Lock Expiration |
draft |
|
Functional Group Lock Endpoint Enforcement |
draft |
|
Lock Priority Preemption |
draft |
|
Lock Requirement Policy |
draft |
|
Vehicle Lock Blocks Child Lock Acquisition |
draft |
|
MDD Embedded files |
draft |
|
Support for mimetype application/octet-stream |
draft |
|
OpenAPI Documentation |
draft |
|
OpenAPI Schema |
draft |
|
Operations Handling |
draft |
|
Support for non-standard operation order |
draft |
|
Standalone OpenAPI Generator |
draft |
|
Standardized Resource Collection Mapping |
draft |
|
Vehicle Level Operations |
draft |
|
Version Data Endpoint |
draft |
|
Version Info Endpoint |
draft |
|
Version Registration Function |
draft |
|
Local File System Storage Access Implementation |
draft |
|
Default redb Persistence Provider |
draft |
|
Persistence API |
draft |
|
Systemd Watchdog Integration |
draft |
|
Storage Access Abstraction |
draft |
|
The CDA must support configuration of UDS communication as defined in the following table. |
draft |
|
UDS Functional Communication |
draft |
|
UDS Negative Response Code Handling |
draft |
|
UDS Request-Response Flow |
draft |
|
UDS Tester Present |
draft |
Software Architecture
ID |
Title |
Status |
|---|---|---|
CAN Addressing And Configuration |
draft |
|
CAN Discovery And Keep-Alive |
draft |
|
CAN NRC Classification |
draft |
|
CAN Physical ISO-TP Exchange |
draft |
|
Alive Check |
draft |
|
DoIP Communication Parameters |
draft |
|
DoIP Connection Establishment |
draft |
|
DoIP Connection Management |
draft |
|
Diagnostic Message Exchange |
draft |
|
DoIP Error Handling |
draft |
|
DoIP Message Framing |
draft |
|
DoIP Protocol Version Support |
draft |
|
Routing Activation |
draft |
|
TLS Connection Support |
draft |
|
Spontaneous VAM Handling Mode |
draft |
|
Vehicle Identification |
draft |
|
Database Loading |
draft |
|
Communication Initialization Mode |
draft |
|
DoIP Gateway Initialization |
draft |
|
ECU Discovery |
draft |
|
ECU List Persistence |
draft |
|
ECU List Persistence - Shutdown Update |
draft |
|
ECU States |
draft |
|
Startup Error Handling |
draft |
|
Health Monitoring |
draft |
|
Startup Sequence |
draft |
|
Variant Detection |
draft |
|
Diagnostic Database Update Plugin |
draft |
|
DLT Logging |
draft |
|
DLT Logging - Configuration |
draft |
|
DLT Logging - Context Annotation |
draft |
|
Vehicle Topology Plugin - Reset |
draft |
|
Vehicle Topology Plugin - Reset with Persisted List Control |
draft |
|
Vehicle Topology Plugin - Retrieval |
draft |
|
Authentication Endpoints |
draft |
|
Bulk-Data Endpoints |
draft |
|
Communication Control Endpoints |
draft |
|
Communication Parameters API |
draft |
|
Retrieve Communication Parameters without Lock |
draft |
|
Component SDG/SDs |
draft |
|
Components Entity Collection |
draft |
|
Configuration Resources |
draft |
|
Data Identifier Categories |
draft |
|
Data Resources |
draft |
|
ODX to JSON data type mapping |
draft |
|
DTC Setting Endpoints |
draft |
|
ECU Resource Collection |
draft |
|
ECU Variant Detection via SOVD-API |
draft |
|
Faults endpoint |
draft |
|
Flash data transfer |
draft |
|
Management of flash files |
draft |
|
Flash folder configuration |
draft |
|
Functional Communication API |
draft |
|
Functional Communication - Data |
draft |
|
Diagnostic description & Configuration |
draft |
|
Functional Communication ECU-Lock behavior |
draft |
|
Functional Communication - Modes |
draft |
|
Functional Communication - Operations |
draft |
|
Generic Service Endpoint |
draft |
|
SOVD-API over HTTP |
draft |
|
Lock Acquisition Policy |
draft |
|
Lock API |
draft |
|
Defunct Lock Lifecycle |
draft |
|
HTTP 409 for Preempted Clients |
draft |
|
ECU Lock Endpoint Enforcement |
draft |
|
Lock Exclusivity |
draft |
|
Lock Exclusivity Policy |
draft |
|
Lock Expiration |
draft |
|
Functional Group Lock Endpoint Enforcement |
draft |
|
Lock Priority Mechanism Interface |
draft |
|
Lock Requirement Policy |
draft |
|
Vehicle Lock Blocks Child Lock Acquisition |
draft |
|
MDD Embedded Files API |
draft |
|
Synchronous and Asynchronous Operations |
draft |
|
Security Access Endpoints |
draft |
|
Session Endpoints |
draft |
|
Single ECU Jobs Extension |
draft |
|
Standardized Resource Collection Mapping |
draft |
|
API Version Endpoint Registration Function |
draft |
|
Default redb Persistence Provider |
draft |
|
Persistence API |
draft |
|
Systemd Watchdog Integration |
draft |
|
Storage Access API |
draft |
|
UDS Communication Parameters |
draft |
|
UDS Functional Communication |
draft |
|
UDS NRC Handling |
draft |
|
UDS Request-Response Flow |
draft |
|
UDS Tester Present |
draft |
Detailed Design
ID |
Title |
Status |
|---|---|---|
GET /data/{service} SDG handler |
||
GET /operations/{service} SDG handler |
||
GET /components/{ecu} SDG handler |
||
PUT endpoint for ECU variant detection |
||
Starts HTTP Server |
||
Register Version Endpoint |
||
Atomic commit of a staged transaction via WAL and backup-rename |
||
Startup recovery of interrupted transactions from the WAL |
||
Local filesystem implementation of the Storage Access API |
||
Write-ahead log with checksum-verified one-phase commit |
||
Systemd Watchdog Integration |
Implementation
ID |
Title |
Status |
|---|---|---|
GET /data/{service} SDG handler |
||
GET /operations/{service} SDG handler |
||
GET /components/{ecu} SDG handler |
||
PUT endpoint for ECU variant detection |
||
Starts HTTP Server |
||
Register Version Endpoint |
||
Atomic commit of a staged transaction via WAL and backup-rename |
||
Startup recovery of interrupted transactions from the WAL |
||
Local filesystem implementation of the Storage Access API |
||
Write-ahead log with checksum-verified one-phase commit |
||
Systemd Watchdog Integration |
Unit Tests
ID |
Title |
Status |
|---|---|---|
Recovery cleans up orphaned backup files left after a successful commit |
||
Recovery discards a WAL with a corrupt checksum during the recording phase |
||
test~storage-atomicity-recovery-discards-recording-phase-crash |
Recovery discards an incomplete transaction that crashed while still recording |
|
Recovery removes an empty collection directory left by an interrupted `CreateCollection` commit |
||
Recovery removes a newly-written file left by an interrupted commit with no backup to restore |
||
test~storage-atomicity-recovery-removes-orphaned-collection-dir |
Recovery fully rolls back a multi-operation transaction that created a collection and wrote into it |
|
Recovery restores the original file from its backup after an interrupted overwrite |
||
WAL entries round-trip through checksum-verified encode/decode |
||
WAL reader detects and stops at a truncated entry |
||
Systemd Watchdog Health Aggregation Tests |
Integration Tests
ID |
Title |
Status |
|---|---|---|
ECU-level SDG retrieval (alias param) |
||
Data-level SDG retrieval |
||
Operation-level SDG retrieval |
||
ECU-level SDG retrieval |
||
Version Endpoint Integration Test |