bootstrap mdBook setup

see https://rust-lang.github.io/mdBook/guide/creating.html

Signed-off-by: Daniel Maslowski <[email protected]>

.github/workflows/gh-pages.yml

@@ -0,0 +1,30 @@
+name: github pages
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-20.04
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Setup mdBook
+        uses: peaceiris/actions-mdbook@v2
+        with:
+          mdbook-version: '0.4.40'
+          # mdbook-version: 'latest'
+
+      - run: mdbook build
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        if: ${{ github.ref == 'refs/heads/main' }}
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./book

.gitignore

@@ -1 +1 @@
-*~
+book

README.md

@@ -9,25 +9,11 @@ This is the official site of documentation for the LinuxBoot project. The book
 provides guidance on how to get started, and gives overviews and
 background on the different aspects of LinuxBoot.
 
-## Table of Contents
+## Contributing
 
-|Chapter|   Title|
-|:-----:|:--------------|
-| [1](README.md)|   Overview and Table of Contents|
-| [2](intro/README.md)|   LinuxBoot Introduction|
-| [2a](getting_started/README.md)|   Getting Started|
-| [3](components/README.md)|   LinuxBoot Components|
-| [4](u-root/README.md)|   All about u-root|
-| [5](utilities/README.md)|   LinuxBoot utilities|
-| [5a](UEFI_Tool_Kit/README.md)|   UEFI Tool Kit|
-| [5b](cpu/README.md)|   The magical cpu command|
-| [5c](dut/README.md)|   Device Under Test|
-| [6](implementation/README.md)|   Implementing LinuxBoot|
-| [6a](coreboot.u-root.systemboot/README.md)|   LinuxBoot using coreboot, u-root and systemboot|
-| [7](glossary/README.md)|   Glossary|
-| [8](naming/README.md) |   Naming|
-| [9](case_studies/README.md)|   Case Studies|
-| [10](faq/README.md)|   Frequently Asked Questions|
+This book is written with [mdBook](https://github.com/rust-lang/mdBook).
+When installed, run `mdbook serve` and you will get a local webserver.
+For more details, please refer to the mdBook documentation.
 
 ## Acknowledgments
 

book.toml

@@ -0,0 +1,6 @@
+[book]
+authors = ["LinuxBoot authors"]
+language = "en"
+multilingual = false
+src = "src"
+title = "LinuxBoot"

src/SUMMARY.md

@@ -0,0 +1,16 @@
+- [LinuxBoot Introduction](intro.md)
+  * [Getting Started](getting_started.md)
+- [LinuxBoot Components](components.md)
+- [All about u-root](u-root.md)
+- [LinuxBoot utilities](utilities/index.md)
+  * [UEFI Tool Kit](utilities/UEFI_Tool_Kit.md)
+  * [The magical cpu command](utilities/cpu.md)
+  * [Device Under Test](utilities/dut.md)
+- [Implementing LinuxBoot](implementation.md)
+  * [LinuxBoot using coreboot, u-root and systemboot](coreboot.u-root.systemboot/index.md)
+- [Glossary](glossary.md)
+- [Naming](naming.md)
+- [Case Studies](case_studies/index.md)
+  * [Google study](case_studies/Google_study.md)
+  * [OCP TiogaPass](case_studies/TiogaPass.md)
+- [Frequently Asked Questions](faq.md)

case_studies/Google_study/README.md → src/case_studies/Google_study.md

@@ -4,7 +4,7 @@ Google runs workloads across a number of clusters each with up to tens of
 thousands of machines. Firmware runs on these machines when they first start
 up. Google is pushing the state-of-the-art in many places including firmware.
 The discussion here about Google's implementation of LinuxBoot is limited to
-replacing specific UEFI [firmware](https://github.com/linuxboot/book/blob/master/intro/glossary/README.md)
+replacing specific UEFI [firmware](../glossary.md)
 functionality with a Linux kernel and runtime. Over the years this project
 has grown to include various initiatives with the overarching goal of moving
 from obscure, complex firmware to simpler, open source firmware.
@@ -35,7 +35,7 @@ In UEFI systems, LinuxBoot consists of a "full stack" solution
 of stripped-down UEFI firmware, a Linux kernel, and an initramfs with
 tools written in Go. Although these components all make up one bundle
 stored in ROM, there are three parts: the closed-source EFI firmware,
-a Linux kernel, and [u-root](../../u-root/README.md). The Linux kernel is
+a Linux kernel, and [u-root](../u-root.md). The Linux kernel is
 an unmodified kernel.  The user-space initramfs image with Go tools
 for system booting is available as u-root. Due to this modularity,
 LinuxBoot can be used with a variety of systems. In many cases,
@@ -86,26 +86,26 @@ Step 1. Reduce or replace UEFI components
    The dark <span style="color:blue">blue</span> items on the left
    cannot be changed.
 
-<img src="../../images/Case-study-step1.svg" width=600px>
+<img src="../images/Case-study-step1.svg" width=600px>
 
 In the real FLASH part, the SEC and PEI are actually only 10% of total,
 so we reduce the size of those boxes in this and following diagrams.
 
-<img src="../../images/Case-study-step1a.svg" width=600px>
+<img src="../images/Case-study-step1a.svg" width=600px>
 
 Another part of the conversion process was to modify the UEFI boot
 process to boot a LinuxBoot image as shown below.
 
-<img src="../../images/Case-study-step1b.svg" width=600px>
+<img src="../images/Case-study-step1b.svg" width=600px>
 
 Step 2. Delete or replace as many proprietary DXEs as required to make
    step 3 work. In most cases, none need to be removed.
 
-<img src="../../images/Case-study-step2.svg" width=600px>
+<img src="../images/Case-study-step2.svg" width=600px>
 
 Step 3. Replace the UEFI shell with a Linux kernel + u-root
 
-<img src="../../images/Case-study-step3.svg" width=600px>
+<img src="../images/Case-study-step3.svg" width=600px>
 
 When Linux boots it needs a root file system with utilities.
 LinuxBoot provides a file system based on u-root standard
@@ -132,7 +132,7 @@ Step 4. Through trial and error, continue to remove DXEs until you
       other controls, and there is no chance of ever bringing
       them to open source.
 
-<img src="../../images/Case-study-step4.svg" width=600px>
+<img src="../images/Case-study-step4.svg" width=600px>
 
 Step 5. Replace closed source DXEs with open source
 
@@ -141,7 +141,7 @@ If we can build a DXE from source, we can use `utk` to:
 *  Remove the proprietary one
 *  Replace it with one built from source
 
-<img src="../../images/Case-study-step5.svg" width=600px>
+<img src="../images/Case-study-step5.svg" width=600px>
 
 Step 6. Next steps: complete LinuxBoot
 
@@ -155,5 +155,5 @@ does the following:
 
 The complete LinuxBoot solution is shown in the following diagram.
 
-<img src="../../images/Case-study-step6.svg" width=600px>
+<img src="../images/Case-study-step6.svg" width=600px>
 

case_studies/README.md → src/case_studies/index.md

@@ -4,5 +4,5 @@ This chapter contains case studies for various solutions.
 
 ## Table of Contents
 
-1. [Google_study](Google_study/README.md)
-1. [OCP TiogaPass](TiogaPass/README.md)
+1. [Google study](Google_study.md)
+1. [OCP TiogaPass](TiogaPass.md)

implementation/README.md → src/implementation.md

@@ -23,7 +23,7 @@ UEFI has three sections:
 DXE process is very complex; some systems have 750 DXEs.
 
 LinuxBoot replaces most of the UEFI software with Linux. LinuxBoot has an
-initramfs provided by [u-root](../u-root/README.md).
+initramfs provided by [u-root](../u-root.md).
 
 The above are stored inside a flash filesystem (FFS) inside a region of flash
 on your motherboard (the BIOS region). Another important region of flash is the

intro/README.md → src/intro.md

@@ -11,7 +11,7 @@ This is the official “LinuxBoot Book” for the LinuxBoot project. The book:
 
 ## What is LinuxBoot?
 
-LinuxBoot is a project that aims to replace specific [firmware](../glossary/README.md) functionality with a Linux kernel and runtime. Over the years this project has grown to include various initiatives with the overarching goal of moving from obscure, complex firmware to simpler, open source firmware.
+LinuxBoot is a project that aims to replace specific [firmware](./glossary.md) functionality with a Linux kernel and runtime. Over the years this project has grown to include various initiatives with the overarching goal of moving from obscure, complex firmware to simpler, open source firmware.
 
 The goal of LinuxBoot is to reduce the role of firmware to a small, fixed-function core whose only purpose is to get a flash-based Linux kernel started. This “bare essentials” firmware prepares the hardware and starts a Linux kernel and a userland environment will run on the machine. Go is the recommended userland environment, but is not required.