diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml new file mode 100644 index 0000000..f5a40fb --- /dev/null +++ b/.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 diff --git a/.gitignore b/.gitignore index b25c15b..7585238 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1 @@ -*~ +book diff --git a/README.md b/README.md index 98e6151..c5891d9 100644 --- a/README.md +++ b/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 diff --git a/book.toml b/book.toml new file mode 100644 index 0000000..f53a0b6 --- /dev/null +++ b/book.toml @@ -0,0 +1,6 @@ +[book] +authors = ["LinuxBoot authors"] +language = "en" +multilingual = false +src = "src" +title = "LinuxBoot" diff --git a/case_studies/ocp-wedge-100s.md b/case_studies/ocp-wedge-100s.md deleted file mode 100644 index 20bf2ad..0000000 --- a/case_studies/ocp-wedge-100s.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -description: >- - This article is about setting up the OCP Wedge 100s with coreboot and multiple - LinuxBoot payloads ---- - -# OCP Wedge 100s - -## Getting Started - - - - - diff --git a/src/SUMMARY.md b/src/SUMMARY.md new file mode 100644 index 0000000..c32a194 --- /dev/null +++ b/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) diff --git a/case_studies/Google_study/README.md b/src/case_studies/Google_study.md similarity index 90% rename from case_studies/Google_study/README.md rename to src/case_studies/Google_study.md index 501ca20..12ca5c7 100644 --- a/case_studies/Google_study/README.md +++ b/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 blue items on the left cannot be changed. - + 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. - + Another part of the conversion process was to modify the UEFI boot process to boot a LinuxBoot image as shown below. - + Step 2. Delete or replace as many proprietary DXEs as required to make step 3 work. In most cases, none need to be removed. - + Step 3. Replace the UEFI shell with a Linux kernel + u-root - + 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. - + 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 - + Step 6. Next steps: complete LinuxBoot @@ -155,5 +155,5 @@ does the following: The complete LinuxBoot solution is shown in the following diagram. - + diff --git a/case_studies/TiogaPass/README.md b/src/case_studies/TiogaPass.md similarity index 100% rename from case_studies/TiogaPass/README.md rename to src/case_studies/TiogaPass.md diff --git a/case_studies/README.md b/src/case_studies/index.md similarity index 54% rename from case_studies/README.md rename to src/case_studies/index.md index 93bd222..60f7ccf 100644 --- a/case_studies/README.md +++ b/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) diff --git a/case_studies/TiogaPass/linux_config b/src/case_studies/linux_config similarity index 100% rename from case_studies/TiogaPass/linux_config rename to src/case_studies/linux_config diff --git a/components/README.md b/src/components.md similarity index 100% rename from components/README.md rename to src/components.md diff --git a/coreboot.u-root.systemboot/README.md b/src/coreboot.u-root.systemboot/index.md similarity index 100% rename from coreboot.u-root.systemboot/README.md rename to src/coreboot.u-root.systemboot/index.md diff --git a/coreboot.u-root.systemboot/linux-4.19.6-linuxboot.config b/src/coreboot.u-root.systemboot/linux-4.19.6-linuxboot.config similarity index 100% rename from coreboot.u-root.systemboot/linux-4.19.6-linuxboot.config rename to src/coreboot.u-root.systemboot/linux-4.19.6-linuxboot.config diff --git a/faq/README.md b/src/faq.md similarity index 100% rename from faq/README.md rename to src/faq.md diff --git a/getting_started/README.md b/src/getting_started.md similarity index 100% rename from getting_started/README.md rename to src/getting_started.md diff --git a/glossary/README.md b/src/glossary.md similarity index 100% rename from glossary/README.md rename to src/glossary.md diff --git a/images/Case-study-step1.svg b/src/images/Case-study-step1.svg similarity index 100% rename from images/Case-study-step1.svg rename to src/images/Case-study-step1.svg diff --git a/images/Case-study-step1a.svg b/src/images/Case-study-step1a.svg similarity index 100% rename from images/Case-study-step1a.svg rename to src/images/Case-study-step1a.svg diff --git a/images/Case-study-step1b.svg b/src/images/Case-study-step1b.svg similarity index 100% rename from images/Case-study-step1b.svg rename to src/images/Case-study-step1b.svg diff --git a/images/Case-study-step2.svg b/src/images/Case-study-step2.svg similarity index 100% rename from images/Case-study-step2.svg rename to src/images/Case-study-step2.svg diff --git a/images/Case-study-step3.svg b/src/images/Case-study-step3.svg similarity index 100% rename from images/Case-study-step3.svg rename to src/images/Case-study-step3.svg diff --git a/images/Case-study-step4.svg b/src/images/Case-study-step4.svg similarity index 100% rename from images/Case-study-step4.svg rename to src/images/Case-study-step4.svg diff --git a/images/Case-study-step5.svg b/src/images/Case-study-step5.svg similarity index 100% rename from images/Case-study-step5.svg rename to src/images/Case-study-step5.svg diff --git a/images/Case-study-step6.svg b/src/images/Case-study-step6.svg similarity index 100% rename from images/Case-study-step6.svg rename to src/images/Case-study-step6.svg diff --git a/images/LinuxBoot-components.svg b/src/images/LinuxBoot-components.svg similarity index 100% rename from images/LinuxBoot-components.svg rename to src/images/LinuxBoot-components.svg diff --git a/images/UEFI-versus-LinuxBoot.svg b/src/images/UEFI-versus-LinuxBoot.svg similarity index 100% rename from images/UEFI-versus-LinuxBoot.svg rename to src/images/UEFI-versus-LinuxBoot.svg diff --git a/images/cpu_first_step.svg b/src/images/cpu_first_step.svg similarity index 100% rename from images/cpu_first_step.svg rename to src/images/cpu_first_step.svg diff --git a/images/cpu_overview.svg b/src/images/cpu_overview.svg similarity index 100% rename from images/cpu_overview.svg rename to src/images/cpu_overview.svg diff --git a/images/cpu_second_step.svg b/src/images/cpu_second_step.svg similarity index 100% rename from images/cpu_second_step.svg rename to src/images/cpu_second_step.svg diff --git a/images/cpu_startup.svg b/src/images/cpu_startup.svg similarity index 100% rename from images/cpu_startup.svg rename to src/images/cpu_startup.svg diff --git a/images/cpu_third_step.svg b/src/images/cpu_third_step.svg similarity index 100% rename from images/cpu_third_step.svg rename to src/images/cpu_third_step.svg diff --git a/implementation/README.md b/src/implementation.md similarity index 99% rename from implementation/README.md rename to src/implementation.md index 22c4237..08613a5 100644 --- a/implementation/README.md +++ b/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 diff --git a/intro/README.md b/src/intro.md similarity index 96% rename from intro/README.md rename to src/intro.md index 4fe3105..754e97a 100644 --- a/intro/README.md +++ b/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. diff --git a/naming/README.md b/src/naming.md similarity index 100% rename from naming/README.md rename to src/naming.md diff --git a/u-root/README.md b/src/u-root.md similarity index 100% rename from u-root/README.md rename to src/u-root.md diff --git a/UEFI_Tool_Kit/README.md b/src/utilities/UEFI_Tool_Kit.md similarity index 100% rename from UEFI_Tool_Kit/README.md rename to src/utilities/UEFI_Tool_Kit.md diff --git a/cpu/README.md b/src/utilities/cpu.md similarity index 100% rename from cpu/README.md rename to src/utilities/cpu.md diff --git a/dut/README.md b/src/utilities/dut.md similarity index 100% rename from dut/README.md rename to src/utilities/dut.md diff --git a/utilities/README.md b/src/utilities/index.md similarity index 100% rename from utilities/README.md rename to src/utilities/index.md