Merge pull request #1 from philgweber/main

Added mdbook for setting up QEMU and generic description for README.md

.github/workflows/buildbook.yml

@@ -0,0 +1,36 @@
+# This workflow makes sure we can build all the books successfully
+permissions:
+  contents: read
+on:
+  push:
+    branches: [main]
+  pull_request:
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+name: build-book
+jobs:
+  buildbook:
+    runs-on: ubuntu-latest
+    name: ${{ matrix.target }}
+    strategy:
+      matrix:
+        target: [thumbv8m.main-none-eabihf]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install mdbook
+        run: |
+          curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.12/mdbook-v0.4.12-x86_64-unknown-linux-gnu.tar.gz | tar -xz -C /usr/local/bin
+
+      - name: Build all books
+        run: |
+          for book in $(find . -name book.toml -exec dirname {} \;); do
+            mdbook build $book
+          done
+
+      - name: Upload built books
+        uses: actions/upload-artifact@v4
+        with:
+          name: built-books
+          path: '**/book'
+          if-no-files-found: error

README.md

@@ -1,2 +1,2 @@
-# embedded-rust-template
-Template repository for Embedded Rust development
+# Open Device Partnership Documentation
+This repository contains documentation for Open Device Partnership. We recommend starting from the overview book to understand the organization of the repositories and documentation.

books/qemu/book.toml

@@ -0,0 +1,2 @@
+[book]
+title = "QEMU Setup Guide"

books/qemu/src/README.md

@@ -0,0 +1,6 @@
+# QEMU Setup Guide
+
+## Overview
+This document provides details on how to setup QEMU, boot windows image and enable windbg.
+Next it covers details on how to compile a UEFI image for QEMU and modify ACPI content.
+

books/qemu/src/SUMMARY.md

@@ -0,0 +1,11 @@
+# Summary
+
+[Introduction](README.md)
+
+- [Setting up QEMU](qemu-setup.md)
+    - [Windbg Setup for QEMU](qemu-windbg.md)
+
+- [Compiling UEFI for QEMU](mu-tianocore-build.md)
+    - [ACPI Customization](qemu-acpi.md)
+
+- [Modifying Windows Image](qemu-windows.md)

books/qemu/src/mu-tianocore-build.md

@@ -0,0 +1,36 @@
+# Compiling UEFI for QEMU
+
+## Downloading and Building Image
+
+The following steps will install required packages, setup and build UEFI image for QemuSbsaPkg which is ARM64 image.
+
+```
+git clone https://github.com/microsoft/mu_tiano_platforms.git
+cd mu_tiano_platforms
+git submodule update --init --recursive
+sudo apt-get install python3
+sudo apt-get install python3.10-venv
+python3 -vm venv .venv
+source .venv/bin/activate
+sudo apt-get install python-is-python3
+sudo apt-get install python3-pip
+pip install -r pip-requirements.txt --upgrade
+sudo apt-get install -y build-essential git nasm wget m4 bison flex uuid-dev unzip acpica-tools gcc-multilib
+sudo apt-get install gcc-aarch64-linux-gnu
+sudo apt-get install mono-complete
+sudo apt-get install mtools
+rustup override set nightly
+cargo install cargo-make
+export GCC5_AARCH64_PREFIX=/usr/bin/aarch64-linux-gnu-
+stuart_setup -c Platforms/QemuSbsaPkg/PlatformBuild.py TOOL_CHAIN_TAG=GCC5
+stuart_update -c Platforms/QemuSbsaPkg/PlatformBuild.py TOOL_CHAIN_TAG=GCC5
+stuart_build -c Platforms/QemuSbsaPkg/PlatformBuild.py TOOL_CHAIN_TAG=GCC5
+```
+
+## Running QEMU
+After image has been built you can run the generated image using the following command. This assumes you already have qemu-system-aarch64 compiled and installed on your system.
+```
+stuart_build -c Platforms/QemuSbsaPkg/PlatformBuild.py TOOL_CHAIN_TAG=GCC5 --FlashOnly
+```
+
+This will run to UEFI Shell> and your QEMU is working and running

books/qemu/src/qemu-acpi.md

@@ -0,0 +1,26 @@
+# ACPI Customization
+
+## Adding Test Content to ACPI
+
+ACPI is compiled as part of the MU_TIANOCORE image. To update ACPI you simply need to modify the tables found here in the UEFI build.
+
+`mu_tiano_platforms/Platforms/QemuSbsaPkg/AcpiTables`
+
+Update the dsdt.asl in this folder to include your ACPI content in this case test.asl
+
+```
+...
+    #include "test.asl"
+
+    //
+    // Legacy SOC bus
+    //
+    Device (SOCB) {
+      Name (_HID, "ACPI0004")
+      Name (_UID, 0x0)
+      Name (_CCA, 0x0)
+```
+
+Recompile mu UEFI and it will pick up these ACPI changes in the QEMU_EFI.fd image when you boot QEMU.
+
+<b>Note: </b> ACPI is provided as part of the firmware image so change ACPI does not require you to change your windows image.