Multiple entry points

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

@@ -1,25 +1,20 @@
-# @file publish-mdbook.yml
-#
-# A Github workflow that compiles an mdbook located at guide_book/* and publishes it
-# to the repository's github page.
-#
-name: Build and Publish Guide Book
+name: Build and Publish ODP Books
 
 on:
-  # Trigger this workflow manually if necessary
   workflow_dispatch:
-
-  # Triggers this workflow if a commit is pushed to main in which a file in
-  # bookshelf/** has been updated
   push:
     branches:
       - main
     paths:
       - guide_book/**
+      - tracks/**
+      - .github/workflows/publish-guide-book.yml
+      - tracks/**
+      - .github/workflows/publish-guide-book.yml
 
 jobs:
   build:
-    name: Build Guide Book
+    name: Build All Books
     runs-on: ubuntu-latest
 
     steps:
@@ -29,39 +24,99 @@ jobs:
       - name: Install Rust
         uses: dtolnay/rust-toolchain@stable
 
-      - name: Install MdBook
-        run: cargo install mdbook
-
-      - name: Install Mermaid
-        run: cargo install mdbook-mermaid
+      - name: Install mdBook and Plugins
+        run: |
+          cargo install mdbook
+          cargo install mdbook-mermaid
+
+      - name: Prepare Output Folders
+        run: |
+          mkdir -p .temp/guide
+          mkdir -p .temp/tracks
+      - name: Install mdBook and Plugins
+        run: |
+          cargo install mdbook
+          cargo install mdbook-mermaid
 
-      - name: Build the Guide Book
+      - name: Prepare Output Folders
+        run: |
+          mkdir -p .temp/guide
+          mkdir -p .temp/tracks
+
+      - name: Build Main Guide Book
         run: |
           cd guide_book
+          mdbook clean
+          mdbook clean
           mdbook build
+          cp -r book/* ../.temp/guide/
+
+      - name: Prepare and Build Track Books
+        run: |
+          # Reusable copy function for TOML and mermaid files
+          for TRACK in contributor embedded_controller integrator patina security value_proposition; do
+            cp -r guide_book/book.toml tracks/$TRACK/
+            cp -r guide_book/mermaid* tracks/$TRACK/
+          done
 
-      - name: Upload Github Pages Site Artifact
+          # Shared content for specific tracks
+          mkdir -p tracks/value_proposition/src/why
+          cp -r guide_book/src/why/* tracks/value_proposition/src/why/
+
+          cp -r guide_book/src/intro/concepts/patina.md tracks/patina/src/patina_concepts.md
+
+          cp -r guide_book/src/intro/concepts/Embedded_controller.md tracks/embedded_controller/src/general.md
+          cp -r guide_book/src/architecture/embedded_controller.md tracks/embedded_controller/src/architecture.md
+          cp -r guide_book/src/architecture/ec_components.md tracks/embedded_controller/src/component_arch.md
+          cp -r guide_book/src/architecture/ec_services.md tracks/embedded_controller/src/ec_services_arch.md
+          mkdir -p tracks/embedded_controller/src/images
+          cp -r guide_book/src/intro/concepts/images/simplified_layers.png tracks/embedded_controller/src/images/
+          cp -r guide_book/src/intro/concepts/images/odp_arch.png tracks/embedded_controller/src/images/
+          cp -r guide_book/src/intro/concepts/EC_Services.md tracks/embedded_controller/src/secure_ec_services.md
+
+          cp -r guide_book/src/why/secure_trust.md tracks/security/src/secure_trust.md
+          cp -r guide_book/src/architecture/security_architecture.md tracks/security/src/security_architecture.md
+          cp -r guide_book/src/architecture/secure_boot.md tracks/security/src/secure_boot.md
+          cp -r guide_book/src/architecture/secure_firmware_updates.md tracks/security/src/secure_firmware_updates.md
+          cp -r guide_book/src/architecture/secure_ec_services.md tracks/security/src/secure_ec_services.md
+
+          # Build each track
+          for TRACK in contributor embedded_controller integrator patina security value_proposition; do
+            cd tracks/$TRACK
+            mdbook clean
+            mdbook build
+            mkdir -p ../../.temp/tracks/$TRACK/
+            cp -r book/* ../../.temp/tracks/$TRACK/
+            cd ../..
+          done
+
+      - name: Create Root Redirect to Guide Book
+        run: |
+          echo '<!DOCTYPE html><html><head><meta http-equiv="refresh" content="0; url=guide/index.html"></head><body></body></html>' > .temp/index.html
+
+      - name: Upload Pages Artifact
         uses: actions/upload-pages-artifact@v3
         with:
           name: github-pages
-          path: guide_book/book/
+          path: .temp/
 
   publish:
-    name: Publish Guide Book
-    needs: [build]
+    name: Publish Site
+    needs: build
     runs-on: ubuntu-latest
 
     environment:
-      name: github-pages  # 👈 Required for GitHub Pages deployment
+      name: github-pages
 
     permissions:
       id-token: write
       contents: read
       pages: write
 
     steps:
-      - name: Deploy Github Page
+      - name: Deploy GitHub Pages
         uses: actions/deploy-pages@v4
         with:
           token: ${{ github.token }}
-          artifact_name: github-pages
+          artifact_name: github-pages
+

.gitignore

@@ -13,14 +13,73 @@ Cargo.lock
 # MSVC Windows builds of rustc generate these, which store debugging information
 *.pdb
 
+# VSCODE settings
+.vscode
+
 # Ignore book output
 book
 
 # Ignore local site build 
 .temp/guide
+.temp/tracks
+
+# Ignore common copied files
+# These are copied from the guide book to the tracks
+# and are not needed in the repository
+tracks/advisor/book.toml
+tracks/advisor/mermaid-init.js
+tracks/advisor/mermaid.min.js  
+tracks/contributor/book.toml
+tracks/contributor/mermaid-init.js
+tracks/contributor/mermaid.min.js  
+tracks/embedded_controller/book.toml
+tracks/embedded_controller/mermaid-init.js     
+tracks/embedded_controller/mermaid.min.js
+tracks/engineer/book.toml
+tracks/engineer/mermaid-init.js         
+tracks/engineer/mermaid.min.js
+tracks/integrator/book.toml
+tracks/integrator/mermaid-init.js
+tracks/integrator/mermaid.min.js
+tracks/patina/book.toml
+tracks/patina/mermaid-init.js       
+tracks/patina/mermaid.min.js
+tracks/security/book.toml
+tracks/security/mermaid-init.js
+tracks/security/mermaid.min.js
+tracks/value_proposition/book.toml  
+tracks/value_proposition/mermaid-init.js
+tracks/value_proposition/mermaid.min.js
+
+tracks/embedded_controller/src/general.md
+tracks/embedded_controller/src/architecture.md
+tracks/embedded_controller/src/component_arch.md
+tracks/embedded_controller/src/ec_services_arch.md
+tracks/embedded_controller/src/images/
+tracks/embedded_controller/src/secure_ec_services.md
+
+tracks/security/src/secure_trust.md
+tracks/security/src/security_architecture.md
+tracks/security/src/secure_boot.md
+tracks/security/src/secure_firmware_updates.md
+tracks/security/src/secure_ec_services.md
+
+# Ignore files duplicated for 'tracks'
+tracks\value_proposition\src\why
+tracks\patina\src\patina_concepts.md
+
+tracks\embedded_controller\src\general.md
+tracks\embedded_controller\src\architecture.md
+tracks\embedded_controller\src\component_arch.md
+tracks\embedded_controller\src\ec_services_arch.md
+tracks\embedded_controller\src\images
+
+tracks\security\src\secure_trust.md
+tracks\security\src\security_architecture.md
+tracks\security\src\secure_boot.md
+tracks\security\src\secure_firmware_updates.md
+tracks\security\src\secure_ec_services.md
 
-# Ignore file generated by mdbook for return to library in inde
-bookshelf/Shelf\ 4\ Specifications/library.html
 
 # Ignore local notes
 cheat_sheet.md

.temp/build.bat

@@ -1,12 +1,70 @@
 REM make book
+md .temp
+md .temp\guide
+md .temp\tracks  
 cd guide_book
 mdbook clean
 mdbook build
+REM move into place
+xcopy "book\*" ".\..\.temp\guide" /E /I /Y
 
-REM build site directory
-cd ..\
-md .\.temp
-cd .\.temp
-md .\guide
-cd ..\guide_book
-xcopy "book\*" "..\.temp\guide" /E /I /Y
+REM copy the common toml and mermaid files
+copy ".\book.toml" "..\tracks\contributor\" /Y
+copy ".\mermaid*" "..\tracks\contributor\" /Y
+copy ".\book.toml" "..\tracks\embedded_controller\" /Y    
+copy ".\mermaid*" "..\tracks\embedded_controller\" /Y
+copy ".\book.toml" "..\tracks\integrator\" /Y
+copy ".\mermaid*" "..\tracks\integrator\" /Y
+copy ".\book.toml" "..\tracks\patina\" /Y 
+copy ".\mermaid*" "..\tracks\patina\" /Y
+copy ".\book.toml" "..\tracks\security\" /Y
+copy ".\mermaid*" "..\tracks\security\" /Y
+copy ".\book.toml" "..\tracks\value_proposition\" /Y
+copy ".\mermaid*" "..\tracks\value_proposition\" /Y
+
+REM copy content shared across tracks
+xcopy ".\src\why\*" "..\tracks\value_proposition\src\why" /E /I /Y
+xcopy ".\src\intro\concepts\patina.md" "..\tracks\patina\src\patina_concepts.md" /E /I /Y
+
+copy ".\src\intro\concepts\Embedded_controller.md" "..\tracks\embedded_controller\src\general.md" /Y
+copy ".\src\architecture\embedded_controller.md" "..\tracks\embedded_controller\src\architecture.md" /Y
+copy ".\src\architecture\ec_components.md" "..\tracks\embedded_controller\src\component_arch.md" /Y
+copy ".\src\architecture\ec_services.md" "..\tracks\embedded_controller\src\ec_services_arch.md" /Y
+md "..\tracks\embedded_controller\src\images"
+copy ".\src\intro\concepts\images\simplified_layers.png" "..\tracks\embedded_controller\src\images\simplified_layers.png" /Y
+copy ".\src\intro\concepts\images\odp_arch.png" "..\tracks\embedded_controller\src\images\odp_arch.png" /Y
+copy ".\src\intro\concepts\EC_Services.md" "..\tracks\embedded_controller\src\secure_ec_services.md" /Y
+
+copy ".\src\why\secure_trust.md" "..\tracks\security\src\secure_trust.md" /Y
+copy ".\src\architecture\security_architecture.md" "..\tracks\security\src\security_architecture.md" /Y
+copy ".\src\architecture\secure_boot.md" "..\tracks\security\src\secure_boot.md" /Y
+copy ".\src\architecture\secure_firmware_updates.md" "..\tracks\security\src\secure_firmware_updates.md" /Y
+copy ".\src\architecture\secure_ec_services.md" "..\tracks\security\src\secure_ec_services.md" /Y
+
+
+
+REM make all track books and copy into place
+cd ..\tracks\contributor
+mdbook clean                
+mdbook build
+xcopy "book\*" "..\..\.temp\tracks\contributor" /E /I /Y
+cd ..\embedded_controller
+mdbook clean
+mdbook build
+xcopy "book\*" "..\..\.temp\tracks\embedded_controller" /E /I /Y
+cd ..\integrator
+mdbook clean        
+mdbook build
+xcopy "book\*" "..\..\.temp\tracks\integrator" /E /I /Y
+cd ..\patina
+mdbook clean
+mdbook build
+xcopy "book\*" "..\..\.temp\tracks\patina" /E /I /Y
+cd ..\security
+mdbook clean    
+mdbook build
+xcopy "book\*" "..\..\.temp\tracks\security" /E /I /Y
+cd ..\value_proposition
+mdbook clean    
+mdbook build   
+xcopy "book\*" "..\..\.temp\tracks\value_proposition" /E /I /Y

guide_book/src/SUMMARY.md

@@ -6,7 +6,8 @@
     - [Developer Experience](./why/developer_experience.md)
     - [Sustainability and Cost](./why/sustainability.md)
     - [Industry Standards](./why/standards.md)
-- [Introduction](./intro/welcome.md)
+- [Introduction](./intro/getting_started.md)
+    - [Welcome Developer](./intro/welcome.md)
     - [Concepts](./intro/concepts/Concepts.md)
         - [A Quick Look at Rust](./intro/concepts/rust_quick_look.md)
         - [Patina](./intro/concepts/patina.md)
@@ -21,6 +22,16 @@
             - [Button](./intro/tutorial/UserButton.md)
             - [Listener](./intro/tutorial/LEDApi.md)
             - [Logic](./intro/tutorial/Logic.md)
+- [Architecture](./architecture/architecture.md)
+    - [Patina Framework](./architecture/patina_framework.md)
+        - [Component Model](./architecture/patina_components.md)    
+    - [Embedded Controller](./architecture/embedded_controller.md)
+        - [Component Model](./architecture/ec_components.md)
+    - [EC Services](./architecture/ec_services.md)
+    - [Security Model](./architecture/security_architecture.md)
+        - [Secure Boot](./architecture/secure_boot.md)
+        - [Firmware Updates](./architecture/secure_firmware_updates.md)
+        - [Secure EC Services](./architecture/secure_ec_services.md)
 - [Tracks of ODP](./tracks.md)
 - [What is in ODP?](./what/what.md)
 - [Building a virtual laptop](./laptop/laptop.md)
@@ -88,12 +99,12 @@
             - [Integration](./how/ec/integration/integration.md)
                 -[Integration Tests](./how/ec/integration/integration_tests.md)
             - [Embedded Targeting](./how/ec/embedded_target/embedded_targeting.md)
-            - [Project Board](./how/ec/embedded_target/project_board.md)
-            - [Dependencies](./how/ec/embedded_target/embedded_dependencies.md)
-            - [Code Changes](./how/ec/embedded_target/embedded_code_changes.md)
-            - [Logging](./how/ec/embedded_target/embedded_logging.md)
-            - [Flashing](./how/ec/embedded_target/embedded_flashing.md)
-            - [Testing](./how/ec/embedded_target/embedded_testing.md)
+                - [Project Board](./how/ec/embedded_target/project_board.md)
+                - [Dependencies](./how/ec/embedded_target/embedded_dependencies.md)
+                - [Code Changes](./how/ec/embedded_target/embedded_code_changes.md)
+                - [Logging](./how/ec/embedded_target/embedded_logging.md)
+                - [Flashing](./how/ec/embedded_target/embedded_flashing.md)
+                - [Testing](./how/ec/embedded_target/embedded_testing.md)
     - [Integrating the Virtual Laptop](./laptop/integrating.md)
 - [Summary and Takeaways](./conclusions.md)
 
@@ -114,5 +125,3 @@
         - [EC Manufacturing Service](./specs/ec_interface/ec-manufacturing-service.md)
         - [EC OEM Service](./specs/ec_interface/ec-oem-service.md)
         - [Sample System Implementation](./specs/ec_interface/sample-system-implementation.md)
-
-

guide_book/src/architecture/architecture.md

@@ -0,0 +1,22 @@
+# ODP Architecture
+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.
+
+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.
+
+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.
+
+![ODP Architecture Patterns](./media/odp_domains.png)
+> #### Figure: ODP Architecture Across Domains
+> 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. 
+
+
+## Common Patterns of ODP
+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:
+- **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.
+- **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.
+- **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.
+- **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.
+- **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.
+
+
+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.