Skip to content

Commit 89fc4e8

Browse files
haxtibalhaxtibal
committed
Add README
Signed-off-by: Tobias Deiminger <tobias.deiminger@linutronix.de>
1 parent 1b93067 commit 89fc4e8

1 file changed

Lines changed: 110 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# Exploring possibilities for integrating StrictDoc with ELISA’s requirements template approach for the Linux kernel
2+
3+
This demonstrates how to realize the tool-agnostic
4+
[ELISA Kernel Requirements Template](https://docs.google.com/document/d/1c7S7YAledHP2EEQ2nh26Ibegij-XPNuUFkrFLtJPlzs/edit?tab=t.0)
5+
proposal by using [StrictDoc](https://strictdoc.readthedocs.io) as requirements processing tool. The repository contains a filtered (for brevity)
6+
copy of the Linux kernel with requirements and tests from Alessandro Carminat and Gabriele Paoloni ([^1], [^2]) applied on top. ELISA's
7+
[`SPDX-*` tagging scheme]((https://docs.google.com/document/d/1c7S7YAledHP2EEQ2nh26Ibegij-XPNuUFkrFLtJPlzs/edit?tab=t.0#heading=h.9dudo2y6dlhf))
8+
was [added](https://github.com/strictdoc-project/linux-strictdoc/commit/9df9595b) along
9+
with a minimal StrictDoc project configuration.
10+
11+
[^1]: https://lore.kernel.org/all/20250910170000.6475-1-gpaoloni@redhat.com/
12+
[^2]: https://lore.kernel.org/linux-trace-kernel/20250814122206.109096-1-gpaoloni@redhat.com/#r
13+
14+
Go to [rendered requirements](https://strictdoc-project.github.io/linux-strictdoc/).
15+
16+
#### Demonstrated features
17+
18+
- Use `strictdoc export .` to generate a nice
19+
[static HTML document tree](https://strictdoc-project.github.io/linux-strictdoc/linux-strictdoc/Documentation/requirements/charmisc.html)
20+
with visual representation of the
21+
[traceability graph](https://strictdoc-project.github.io/linux-strictdoc/linux-strictdoc/Documentation/requirements/charmisc-TRACE.html#DOC-SUBSYS-CHARMISC),
22+
validation results and full-text search. Other output formats as e.g. PDF are available.
23+
- Compile and validate requirements
24+
[in CI](https://github.com/strictdoc-project/linux-strictdoc/blob/strictdoc/.github/workflows/ci.yaml).
25+
- Parses source code
26+
[SPDX-Req-* tags proposed by ELISA](https://docs.google.com/document/d/1c7S7YAledHP2EEQ2nh26Ibegij-XPNuUFkrFLtJPlzs/edit?tab=t.0#heading=h.9dudo2y6dlhf)
27+
and translates them to StrictDocs internal model.
28+
- Sidecar: Proposed by ELISA to hold additional requirement meta data outside source code. Realized as
29+
[separate sdoc file](https://github.com/strictdoc-project/linux-strictdoc/blob/strictdoc/Documentation/requirements/tracing.sdoc)s
30+
containing requirement stubs. Stubs are merged with source code tags by matching on `SPDX-Req-ID`.
31+
- Use `strictdoc manage auto-assign` to generate SPDX-Req-ID and SPDX-Req-HKey as suggested by Linux kernel
32+
requirements template. The hash generation method is `echo -nE "${PROJECT}${FILE_PATH}${INSTANCE}${CODE}" | sha256sum`.
33+
See [commit 86e7810d](https://github.com/strictdoc-project/linux-strictdoc/commit/86e7810d)
34+
for the auto-generated changes.
35+
- Tracing: Requirements, tests and functions become individual nodes in the traceability graph and are connected
36+
by their stable IDs.
37+
- Custom validations: Use plugin API to
38+
[provide a check](https://github.com/strictdoc-project/linux-strictdoc/blob/strictdoc/tools/requirements/validation_plugin.py#L28)
39+
to see if each requirement has at least one associated test, and each function expectations has at least one dedicated
40+
test.
41+
- Drift detection: As kernel development goes on, occasionally rerun `strictdoc manage auto-assign`. If `SPDX-Req-HKey`
42+
changes, this means that some semantic aspect of the requirement may have changed.
43+
44+
For a thorough documentation of StrictDocs features see
45+
[StrictDoc User Guide ](https://strictdoc.readthedocs.io/en/stable/stable/docs/strictdoc_01_user_guide.html)
46+
47+
#### Usage
48+
49+
```sh
50+
pipx install strictdoc # note: requires strictdoc >= 0.15.1
51+
git clone https://github.com/strictdoc-project/linux-strictdoc
52+
cd linux-strictdoc
53+
strictdoc export . # validate and render to HTML
54+
strictdoc manage auto-uid . # regenerate hashes for drift detection
55+
```
56+
57+
#### Explanation of Content and Processing
58+
59+
```
60+
.
61+
├── Documentation
62+
│ └── requirements
63+
│ ├── charmisc.sdoc # sidecar
64+
│ └── tracing.sdoc # sidecar
65+
├── drivers
66+
│ └── char
67+
│ └── mem.c # Linux code with inlined LLRs
68+
├── kernel
69+
│ └── trace
70+
│ └── trace_events.c # Linux code with inlined LLRs
71+
├── strictdoc_config.py # StrictDoc project configuration
72+
└── tools
73+
├── requirements
74+
│ └── validation_plugin.py # custom requirement validations
75+
└── testing
76+
└── selftests
77+
└── devmem
78+
└── tests.c # tests for /dev/mem LLRs
79+
```
80+
81+
StrictDoc performs the following notable process steps:
82+
- parse \*.sdoc files to create the initial traceability index (a DAG structure)
83+
- parse \*.c files using tree-sitter, read SPDX tags from it and merge it into the DAG
84+
- perform built-in validations and calculate built-in statistics
85+
- perform custom validations
86+
* check if all requirements have at least one related test
87+
* check if all function expectations are mentioned by one related test
88+
- render the DAG into a HTML document tree where all nodes are traceable, including
89+
requirements text, visual graph representation and source code view
90+
91+
#### Handling Fields with Special Meaning but Different Name in StrictDoc / ELISA
92+
93+
The StrictDoc model assigns special meaning to some reserved field names:
94+
- `UID` Unique, human-readable. May change during requirement life-cycle. Used to refer to child/parents by default.
95+
- `MID`: Unique, not human-readable, stable. Optionally used to refer to child/parents.
96+
Supports changing the human-readable UID during the requirement life-cycle.
97+
- `HASH`: Hash sum over predefined requirement content. Can be auto-calculated.
98+
- `STATEMENT`: Some document views and import/export formats require to select a "most important"
99+
field from the many fields.
100+
- `COMMENT`: Can occur multiple times within one requirement.
101+
102+
The ELISA requirements template defines similar special meaning for fields, but under different name.
103+
This is solved by two StrictDoc features:
104+
- `ProjectConfig(source_nodes=[SourceNodesEntry(sdoc_to_source_map={<sdoc_name>: <elisa_name>, ...})])` let's you define
105+
a mapping for fields that appearing under a different name in source code tags.
106+
Example: The stable ID appears as `SPDX-Req-ID` in source code comments, but must be named `MID` in sdoc.
107+
- Setting `HUMAN_TITLE` in the grammar lets you define a different display name for a field that has special
108+
StrictDoc meaning. Example: ELISA wants `HASH` to be named `SPDX-Req-HKey`. Since the field appears only in sdoc,
109+
but not in source code, it's enough to define `HUMAN_TITLE: SPDX-Req-HKey` for the `HASH` field.
110+
`sdoc_to_source_map` is not needed in this case.

0 commit comments

Comments
 (0)