docs: add project mdBook

.github/workflows/docs.yml

@@ -0,0 +1,64 @@
+name: Documentation
+
+on:
+  workflow_dispatch:
+  pull_request:
+    paths:
+      - "docs/**"
+      - ".github/workflows/docs.yml"
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - ".github/workflows/docs.yml"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build mdBook
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Install mdBook
+        run: cargo install mdbook --version 0.5.4 --locked
+
+      - name: Install mdbook-mermaid
+        run: cargo install mdbook-mermaid --version 0.17.1 --locked
+
+      - name: Build documentation
+        run: mdbook build docs
+
+      - name: Upload GitHub Pages artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: docs/book
+
+  deploy:
+    name: Deploy GitHub Pages
+    if: github.event_name == 'push' && github.repository_owner == 'OpenDevicePartnership'
+    needs: build
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      id-token: write
+      pages: write
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

.gitignore

@@ -2,6 +2,7 @@
 # will have compiled files and executables
 debug/
 target/
+docs/book/
 
 # These are backup files generated by rustfmt
 **/*.rs.bk

README.md

@@ -5,6 +5,11 @@
 This is a sample implementation of the EC service which runs under a dedicated secure partition in Hafnium.
 It is written in Rust and has dependencies on FF-A, MU UEFI, Hafnium and TFA.
 
+## Documentation
+
+Project documentation is maintained in the [mdBook source](docs/src/SUMMARY.md)
+and published through GitHub Pages.
+
 ## Feature Status
 
 The following components are available within this crate:

docs/book.toml

@@ -0,0 +1,19 @@
+[book]
+authors = ["Open Device Partnership"]
+language = "en"
+src = "src"
+title = "ODP Secure Services"
+
+[build]
+build-dir = "book"
+
+[preprocessor.mermaid]
+command = "mdbook-mermaid"
+
+[output.html]
+additional-js = ["mermaid.min.js", "mermaid-init.js"]
+git-repository-url = "https://github.com/OpenDevicePartnership/odp-secure-services"
+edit-url-template = "https://github.com/OpenDevicePartnership/odp-secure-services/edit/main/docs/{path}"
+
+[output.html.fold]
+enable = true

docs/mermaid-init.js

@@ -0,0 +1,39 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+(() => {
+    const darkThemes = ['ayu', 'navy', 'coal'];
+    const lightThemes = ['light', 'rust'];
+
+    const classList = document.getElementsByTagName('html')[0].classList;
+
+    let lastThemeWasLight = true;
+    for (const cssClass of classList) {
+        if (darkThemes.includes(cssClass)) {
+            lastThemeWasLight = false;
+            break;
+        }
+    }
+
+    const theme = lastThemeWasLight ? 'default' : 'dark';
+    mermaid.initialize({ startOnLoad: true, theme });
+
+    // Simplest way to make mermaid re-render the diagrams in the new theme is via refreshing the page
+
+    for (const darkTheme of darkThemes) {
+        document.getElementById('mdbook-theme-' + darkTheme).addEventListener('click', () => {
+            if (lastThemeWasLight) {
+                window.location.reload();
+            }
+        });
+    }
+
+    for (const lightTheme of lightThemes) {
+        document.getElementById('mdbook-theme-' + lightTheme).addEventListener('click', () => {
+            if (!lastThemeWasLight) {
+                window.location.reload();
+            }
+        });
+    }
+})();

docs/src/SUMMARY.md

@@ -0,0 +1,3 @@
+# Summary
+
+- [Secure EC Services](secure_ec_services.md)

docs/src/secure_ec_services.md

@@ -0,0 +1,33 @@
+# Secure EC Services
+
+```mermaid
+flowchart TD
+    subgraph Host System
+        A1[ACPI Methods]
+        A2[ACPI Notification Events]
+    end
+
+    subgraph Secure World
+        B1["Hafnium (FFA Handler)"]
+    end
+
+    subgraph EC
+        C1[EC Dispatcher]
+        C2[Subsystem Controller]
+    end
+
+    A1 -->|"Secure Path (ARM/FFA)"| B1
+    A2 -->|Notifications| B1
+    B1 -->|Structured Command| C1
+    C1 --> C2
+
+    A1 -->|"Non-Secure (x86)"| C1
+```
+
+> **Figure: Host-EC Communication Paths**
+>
+> The host communicates with the EC via **ACPI** calls and notification
+> events. On **ARM** platforms with secure world enforcement, messages are
+> routed through **Hafnium** via **FF-A** interfaces. On **x86** platforms,
+> communication is direct. The EC dispatcher then forwards commands to
+> appropriate subsystem controllers.