Skip to content

Commit 925d2e9

Browse files
tremhotremho
authored
Multiple entry points (#75)
This PR introduces multiple points of entry into the overall documentation depending upon what "track" of interest a reader may have according to their subject of interest or their primary development role. This re-introduces the concept of multiple markdown "books" being created, similar the original "bookshelf" construction, but the goal here is not to produce a virtual bookshelf of related subjects, but to offer different curated "tours" of the overall documentation, streamlining the journey for those that may not need to read the entire book. Mdbook does not allow repeated references to the same page in the same book, so multiple books are necessary to allow these selective repeats. The publish bat and yml files handle this by copying pages from the main "guide" into the "tracks" content where needed. Additionally, a few new pages are in "tracks" to provide continuity. Also added to the main book is a new "architecture" section that features a number of diagrams. The book is set to flow from the beginning, and a developer-minded reader is advised to read the book from beginning to end, while other interests are advised which sections they might elect to skip over. Existing links to this content Because there are now multiple books, the url paths to the content has moved slightly. Page paths for the main book no longer come from the root, so any previous link to "https://opendevicepartnership.github.io/documentation/~path~" will now need to include "guide" in the path, ("https://opendevicepartnership.github.io/documentation/guide/~path~") The index page at https://opendevicepartnership.github.io/documentation/ will still work -- it is redirected to https://opendevicepartnership.github.io/documentation/guide/index.html. The "getting started" page that I believe is currently linked to at https://opendevicepartnership.github.io/documentation/intro/welcome.html should be changed to https://opendevicepartnership.github.io/documentation/guide/intro/getting_started.html to represent the new arrangement. Note that prior to merge and publishing, a preview publish for this can be found at https://tremho.github.io/odp-documentation/
1 parent 4fef78a commit 925d2e9

File tree

76 files changed

+1586
-71
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

76 files changed

+1586
-71
lines changed

‎.github/workflows/publish-guide-book.yml‎

Lines changed: 79 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,20 @@
1-
# @file publish-mdbook.yml
2-
#
3-
# A Github workflow that compiles an mdbook located at guide_book/* and publishes it
4-
# to the repository's github page.
5-
#
6-
name: Build and Publish Guide Book
1+
name: Build and Publish ODP Books
72

83
on:
9-
# Trigger this workflow manually if necessary
104
workflow_dispatch:
11-
12-
# Triggers this workflow if a commit is pushed to main in which a file in
13-
# bookshelf/** has been updated
145
push:
156
branches:
167
- main
178
paths:
189
- guide_book/**
10+
- tracks/**
11+
- .github/workflows/publish-guide-book.yml
12+
- tracks/**
13+
- .github/workflows/publish-guide-book.yml
1914

2015
jobs:
2116
build:
22-
name: Build Guide Book
17+
name: Build All Books
2318
runs-on: ubuntu-latest
2419

2520
steps:
@@ -29,39 +24,99 @@ jobs:
2924
- name: Install Rust
3025
uses: dtolnay/rust-toolchain@stable
3126

32-
- name: Install MdBook
33-
run: cargo install mdbook
34-
35-
- name: Install Mermaid
36-
run: cargo install mdbook-mermaid
27+
- name: Install mdBook and Plugins
28+
run: |
29+
cargo install mdbook
30+
cargo install mdbook-mermaid
31+
32+
- name: Prepare Output Folders
33+
run: |
34+
mkdir -p .temp/guide
35+
mkdir -p .temp/tracks
36+
- name: Install mdBook and Plugins
37+
run: |
38+
cargo install mdbook
39+
cargo install mdbook-mermaid
3740
38-
- name: Build the Guide Book
41+
- name: Prepare Output Folders
42+
run: |
43+
mkdir -p .temp/guide
44+
mkdir -p .temp/tracks
45+
46+
- name: Build Main Guide Book
3947
run: |
4048
cd guide_book
49+
mdbook clean
50+
mdbook clean
4151
mdbook build
52+
cp -r book/* ../.temp/guide/
53+
54+
- name: Prepare and Build Track Books
55+
run: |
56+
# Reusable copy function for TOML and mermaid files
57+
for TRACK in contributor embedded_controller integrator patina security value_proposition; do
58+
cp -r guide_book/book.toml tracks/$TRACK/
59+
cp -r guide_book/mermaid* tracks/$TRACK/
60+
done
4261
43-
- name: Upload Github Pages Site Artifact
62+
# Shared content for specific tracks
63+
mkdir -p tracks/value_proposition/src/why
64+
cp -r guide_book/src/why/* tracks/value_proposition/src/why/
65+
66+
cp -r guide_book/src/intro/concepts/patina.md tracks/patina/src/patina_concepts.md
67+
68+
cp -r guide_book/src/intro/concepts/Embedded_controller.md tracks/embedded_controller/src/general.md
69+
cp -r guide_book/src/architecture/embedded_controller.md tracks/embedded_controller/src/architecture.md
70+
cp -r guide_book/src/architecture/ec_components.md tracks/embedded_controller/src/component_arch.md
71+
cp -r guide_book/src/architecture/ec_services.md tracks/embedded_controller/src/ec_services_arch.md
72+
mkdir -p tracks/embedded_controller/src/images
73+
cp -r guide_book/src/intro/concepts/images/simplified_layers.png tracks/embedded_controller/src/images/
74+
cp -r guide_book/src/intro/concepts/images/odp_arch.png tracks/embedded_controller/src/images/
75+
cp -r guide_book/src/intro/concepts/EC_Services.md tracks/embedded_controller/src/secure_ec_services.md
76+
77+
cp -r guide_book/src/why/secure_trust.md tracks/security/src/secure_trust.md
78+
cp -r guide_book/src/architecture/security_architecture.md tracks/security/src/security_architecture.md
79+
cp -r guide_book/src/architecture/secure_boot.md tracks/security/src/secure_boot.md
80+
cp -r guide_book/src/architecture/secure_firmware_updates.md tracks/security/src/secure_firmware_updates.md
81+
cp -r guide_book/src/architecture/secure_ec_services.md tracks/security/src/secure_ec_services.md
82+
83+
# Build each track
84+
for TRACK in contributor embedded_controller integrator patina security value_proposition; do
85+
cd tracks/$TRACK
86+
mdbook clean
87+
mdbook build
88+
mkdir -p ../../.temp/tracks/$TRACK/
89+
cp -r book/* ../../.temp/tracks/$TRACK/
90+
cd ../..
91+
done
92+
93+
- name: Create Root Redirect to Guide Book
94+
run: |
95+
echo '<!DOCTYPE html><html><head><meta http-equiv="refresh" content="0; url=guide/index.html"></head><body></body></html>' > .temp/index.html
96+
97+
- name: Upload Pages Artifact
4498
uses: actions/upload-pages-artifact@v3
4599
with:
46100
name: github-pages
47-
path: guide_book/book/
101+
path: .temp/
48102

49103
publish:
50-
name: Publish Guide Book
51-
needs: [build]
104+
name: Publish Site
105+
needs: build
52106
runs-on: ubuntu-latest
53107

54108
environment:
55-
name: github-pages # 👈 Required for GitHub Pages deployment
109+
name: github-pages
56110

57111
permissions:
58112
id-token: write
59113
contents: read
60114
pages: write
61115

62116
steps:
63-
- name: Deploy Github Page
117+
- name: Deploy GitHub Pages
64118
uses: actions/deploy-pages@v4
65119
with:
66120
token: ${{ github.token }}
67-
artifact_name: github-pages
121+
artifact_name: github-pages
122+

‎.gitignore‎

Lines changed: 61 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,14 +13,73 @@ Cargo.lock
1313
# MSVC Windows builds of rustc generate these, which store debugging information
1414
*.pdb
1515

16+
# VSCODE settings
17+
.vscode
18+
1619
# Ignore book output
1720
book
1821

1922
# Ignore local site build
2023
.temp/guide
24+
.temp/tracks
25+
26+
# Ignore common copied files
27+
# These are copied from the guide book to the tracks
28+
# and are not needed in the repository
29+
tracks/advisor/book.toml
30+
tracks/advisor/mermaid-init.js
31+
tracks/advisor/mermaid.min.js
32+
tracks/contributor/book.toml
33+
tracks/contributor/mermaid-init.js
34+
tracks/contributor/mermaid.min.js
35+
tracks/embedded_controller/book.toml
36+
tracks/embedded_controller/mermaid-init.js
37+
tracks/embedded_controller/mermaid.min.js
38+
tracks/engineer/book.toml
39+
tracks/engineer/mermaid-init.js
40+
tracks/engineer/mermaid.min.js
41+
tracks/integrator/book.toml
42+
tracks/integrator/mermaid-init.js
43+
tracks/integrator/mermaid.min.js
44+
tracks/patina/book.toml
45+
tracks/patina/mermaid-init.js
46+
tracks/patina/mermaid.min.js
47+
tracks/security/book.toml
48+
tracks/security/mermaid-init.js
49+
tracks/security/mermaid.min.js
50+
tracks/value_proposition/book.toml
51+
tracks/value_proposition/mermaid-init.js
52+
tracks/value_proposition/mermaid.min.js
53+
54+
tracks/embedded_controller/src/general.md
55+
tracks/embedded_controller/src/architecture.md
56+
tracks/embedded_controller/src/component_arch.md
57+
tracks/embedded_controller/src/ec_services_arch.md
58+
tracks/embedded_controller/src/images/
59+
tracks/embedded_controller/src/secure_ec_services.md
60+
61+
tracks/security/src/secure_trust.md
62+
tracks/security/src/security_architecture.md
63+
tracks/security/src/secure_boot.md
64+
tracks/security/src/secure_firmware_updates.md
65+
tracks/security/src/secure_ec_services.md
66+
67+
# Ignore files duplicated for 'tracks'
68+
tracks\value_proposition\src\why
69+
tracks\patina\src\patina_concepts.md
70+
71+
tracks\embedded_controller\src\general.md
72+
tracks\embedded_controller\src\architecture.md
73+
tracks\embedded_controller\src\component_arch.md
74+
tracks\embedded_controller\src\ec_services_arch.md
75+
tracks\embedded_controller\src\images
76+
77+
tracks\security\src\secure_trust.md
78+
tracks\security\src\security_architecture.md
79+
tracks\security\src\secure_boot.md
80+
tracks\security\src\secure_firmware_updates.md
81+
tracks\security\src\secure_ec_services.md
2182

22-
# Ignore file generated by mdbook for return to library in inde
23-
bookshelf/Shelf\ 4\ Specifications/library.html
2483

2584
# Ignore local notes
2685
cheat_sheet.md

‎.temp/build.bat‎

Lines changed: 65 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,70 @@
11
REM make book
2+
md .temp
3+
md .temp\guide
4+
md .temp\tracks
25
cd guide_book
36
mdbook clean
47
mdbook build
8+
REM move into place
9+
xcopy "book\*" ".\..\.temp\guide" /E /I /Y
510

6-
REM build site directory
7-
cd ..\
8-
md .\.temp
9-
cd .\.temp
10-
md .\guide
11-
cd ..\guide_book
12-
xcopy "book\*" "..\.temp\guide" /E /I /Y
11+
REM copy the common toml and mermaid files
12+
copy ".\book.toml" "..\tracks\contributor\" /Y
13+
copy ".\mermaid*" "..\tracks\contributor\" /Y
14+
copy ".\book.toml" "..\tracks\embedded_controller\" /Y
15+
copy ".\mermaid*" "..\tracks\embedded_controller\" /Y
16+
copy ".\book.toml" "..\tracks\integrator\" /Y
17+
copy ".\mermaid*" "..\tracks\integrator\" /Y
18+
copy ".\book.toml" "..\tracks\patina\" /Y
19+
copy ".\mermaid*" "..\tracks\patina\" /Y
20+
copy ".\book.toml" "..\tracks\security\" /Y
21+
copy ".\mermaid*" "..\tracks\security\" /Y
22+
copy ".\book.toml" "..\tracks\value_proposition\" /Y
23+
copy ".\mermaid*" "..\tracks\value_proposition\" /Y
24+
25+
REM copy content shared across tracks
26+
xcopy ".\src\why\*" "..\tracks\value_proposition\src\why" /E /I /Y
27+
xcopy ".\src\intro\concepts\patina.md" "..\tracks\patina\src\patina_concepts.md" /E /I /Y
28+
29+
copy ".\src\intro\concepts\Embedded_controller.md" "..\tracks\embedded_controller\src\general.md" /Y
30+
copy ".\src\architecture\embedded_controller.md" "..\tracks\embedded_controller\src\architecture.md" /Y
31+
copy ".\src\architecture\ec_components.md" "..\tracks\embedded_controller\src\component_arch.md" /Y
32+
copy ".\src\architecture\ec_services.md" "..\tracks\embedded_controller\src\ec_services_arch.md" /Y
33+
md "..\tracks\embedded_controller\src\images"
34+
copy ".\src\intro\concepts\images\simplified_layers.png" "..\tracks\embedded_controller\src\images\simplified_layers.png" /Y
35+
copy ".\src\intro\concepts\images\odp_arch.png" "..\tracks\embedded_controller\src\images\odp_arch.png" /Y
36+
copy ".\src\intro\concepts\EC_Services.md" "..\tracks\embedded_controller\src\secure_ec_services.md" /Y
37+
38+
copy ".\src\why\secure_trust.md" "..\tracks\security\src\secure_trust.md" /Y
39+
copy ".\src\architecture\security_architecture.md" "..\tracks\security\src\security_architecture.md" /Y
40+
copy ".\src\architecture\secure_boot.md" "..\tracks\security\src\secure_boot.md" /Y
41+
copy ".\src\architecture\secure_firmware_updates.md" "..\tracks\security\src\secure_firmware_updates.md" /Y
42+
copy ".\src\architecture\secure_ec_services.md" "..\tracks\security\src\secure_ec_services.md" /Y
43+
44+
45+
46+
REM make all track books and copy into place
47+
cd ..\tracks\contributor
48+
mdbook clean
49+
mdbook build
50+
xcopy "book\*" "..\..\.temp\tracks\contributor" /E /I /Y
51+
cd ..\embedded_controller
52+
mdbook clean
53+
mdbook build
54+
xcopy "book\*" "..\..\.temp\tracks\embedded_controller" /E /I /Y
55+
cd ..\integrator
56+
mdbook clean
57+
mdbook build
58+
xcopy "book\*" "..\..\.temp\tracks\integrator" /E /I /Y
59+
cd ..\patina
60+
mdbook clean
61+
mdbook build
62+
xcopy "book\*" "..\..\.temp\tracks\patina" /E /I /Y
63+
cd ..\security
64+
mdbook clean
65+
mdbook build
66+
xcopy "book\*" "..\..\.temp\tracks\security" /E /I /Y
67+
cd ..\value_proposition
68+
mdbook clean
69+
mdbook build
70+
xcopy "book\*" "..\..\.temp\tracks\value_proposition" /E /I /Y

‎guide_book/src/SUMMARY.md‎

Lines changed: 18 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,8 @@
66
- [Developer Experience](./why/developer_experience.md)
77
- [Sustainability and Cost](./why/sustainability.md)
88
- [Industry Standards](./why/standards.md)
9-
- [Introduction](./intro/welcome.md)
9+
- [Introduction](./intro/getting_started.md)
10+
- [Welcome Developer](./intro/welcome.md)
1011
- [Concepts](./intro/concepts/Concepts.md)
1112
- [A Quick Look at Rust](./intro/concepts/rust_quick_look.md)
1213
- [Patina](./intro/concepts/patina.md)
@@ -21,6 +22,16 @@
2122
- [Button](./intro/tutorial/UserButton.md)
2223
- [Listener](./intro/tutorial/LEDApi.md)
2324
- [Logic](./intro/tutorial/Logic.md)
25+
- [Architecture](./architecture/architecture.md)
26+
- [Patina Framework](./architecture/patina_framework.md)
27+
- [Component Model](./architecture/patina_components.md)
28+
- [Embedded Controller](./architecture/embedded_controller.md)
29+
- [Component Model](./architecture/ec_components.md)
30+
- [EC Services](./architecture/ec_services.md)
31+
- [Security Model](./architecture/security_architecture.md)
32+
- [Secure Boot](./architecture/secure_boot.md)
33+
- [Firmware Updates](./architecture/secure_firmware_updates.md)
34+
- [Secure EC Services](./architecture/secure_ec_services.md)
2435
- [Tracks of ODP](./tracks.md)
2536
- [What is in ODP?](./what/what.md)
2637
- [Building a virtual laptop](./laptop/laptop.md)
@@ -88,12 +99,12 @@
8899
- [Integration](./how/ec/integration/integration.md)
89100
-[Integration Tests](./how/ec/integration/integration_tests.md)
90101
- [Embedded Targeting](./how/ec/embedded_target/embedded_targeting.md)
91-
- [Project Board](./how/ec/embedded_target/project_board.md)
92-
- [Dependencies](./how/ec/embedded_target/embedded_dependencies.md)
93-
- [Code Changes](./how/ec/embedded_target/embedded_code_changes.md)
94-
- [Logging](./how/ec/embedded_target/embedded_logging.md)
95-
- [Flashing](./how/ec/embedded_target/embedded_flashing.md)
96-
- [Testing](./how/ec/embedded_target/embedded_testing.md)
102+
- [Project Board](./how/ec/embedded_target/project_board.md)
103+
- [Dependencies](./how/ec/embedded_target/embedded_dependencies.md)
104+
- [Code Changes](./how/ec/embedded_target/embedded_code_changes.md)
105+
- [Logging](./how/ec/embedded_target/embedded_logging.md)
106+
- [Flashing](./how/ec/embedded_target/embedded_flashing.md)
107+
- [Testing](./how/ec/embedded_target/embedded_testing.md)
97108
- [Integrating the Virtual Laptop](./laptop/integrating.md)
98109
- [Summary and Takeaways](./conclusions.md)
99110

@@ -114,5 +125,3 @@
114125
- [EC Manufacturing Service](./specs/ec_interface/ec-manufacturing-service.md)
115126
- [EC OEM Service](./specs/ec_interface/ec-oem-service.md)
116127
- [Sample System Implementation](./specs/ec_interface/sample-system-implementation.md)
117-
118-

‎guide_book/src/architecture/architecture.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# ODP Architecture
2+
The __Open Device Partnership (ODP)__ architecture is designed to provide a modular, scalable, and secure framework for developing embedded systems. Rooted in Rust's safety guarantees and shaped by a philosophy of composable components, ODP offers a consistent foundation for both low-level and system-level firmware development.
3+
4+
ODP spans two distinct domains: The __Patina framework__, a Rust-based system for building DXE-style boot firmware, and the __Embedded Controller (EC)__, architecture, supporting microcontroller-based runtime services and coordination.
5+
6+
Though their implementations differ, these domains are united under the ODP model by shared principles and architectural patterns. Together, they promote a unified approach to firmware engineering that emphasizes safety, reuse, and composability.
7+
8+
![ODP Architecture Patterns](./media/odp_domains.png)
9+
> #### Figure: ODP Architecture Across Domains
10+
> The ODP Core expresses a set of shared design patterns -- such as modularity, safety, and flexibility -- that are applied independently within two distinct ecosystems: Patina (x86 firmware) and Embedded Controller (μC runtime). Each domain develops its own components, tooling, and conventions while adhering to the same architectural principles.
11+
12+
13+
## Common Patterns of ODP
14+
While Patina and EC serve different ends of the firmware spectrum, they share a common set of patterns and priorities that define the ODP approach:
15+
- **Modularity**: ODP components are explicitly modular. Each unit is independently defined and can be composed into larger systems through clearly defined interfaces. This is central to the dependency-injection models used by both Patina and EC's service registry architecture.
16+
- **Safety**: Rust’s type system and ownership model are used to enforce memory and concurrency safety at compile time. This baseline ensures that ODP firmware avoids common pitfalls typical of C-based implementations.
17+
- **Reusability**: Components are designed to be reusable across platforms, configurations, and targets. Traits and message interfaces abstract functionality, enabling code reuse without sacrificing clarity or safety.
18+
- **Flexibility**: The ODP structure supports adaptation to a wide variety of host platforms and runtime environments. This flexibility allows implementers to scale from minimal EC services up to full boot firmware stacks.
19+
- **Community**: ODP is built on open standards and community contributions. This encourages collaboration, knowledge sharing, and the evolution of best practices across the ecosystem, which only enhances the robustness of the architecture and its promises of safety and modularity.
20+
21+
22+
The Open Device Partnership is founded more upon _alignment_ than _unification_ and is supported and extended by the principles of a strong Open Source community, where it will expand and evolve.

0 commit comments

Comments
 (0)