Pmolloy/mdl all the things

src/SUMMARY.md

@@ -1,16 +1,16 @@
 - [LinuxBoot Introduction](intro.md)
-  * [Getting Started](getting_started.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)
+  - [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)
+  - [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)
+  - [Google study](case_studies/Google_study.md)
+  - [OCP TiogaPass](case_studies/TiogaPass.md)
 - [Frequently Asked Questions](faq.md)

src/case_studies/Google_study.md

@@ -14,13 +14,13 @@ from obscure, complex firmware to simpler, open source firmware.
 There have been a number of contributors to the Google LinuxBoot project
 including:
 
--  Ron Minnich (technical lead)
--  Gan-shun Lim
--  Ryan O'Leary
--  Prachi Laud
--  Chris Koch
--  Xuan Chen
--  Andrew Sun
+- Ron Minnich (technical lead)
+- Gan-shun Lim
+- Ryan O'Leary
+- Prachi Laud
+- Chris Koch
+- Xuan Chen
+- Andrew Sun
 
 Ryan O'Leary is one of the Open Compute Platform Foundation
 [Open System Firmware project](https://www.opencompute.org/projects/open-system-firmware)
@@ -64,7 +64,7 @@ of the UEFI, but takes over after that point, replacing the
 UEFI drivers. It therefore completely replaces a large portion
 of the boot process.
 
-# Phases of the project
+## Phases of the project
 
 Google's LinuxBoot project is focused on moving UEFI boot functionality
 into the kernel and userspace. That is, converting UEFI firmware
@@ -83,7 +83,7 @@ Step 1. Reduce or replace UEFI components
    The following diagram shows the phases of the UEFI boot process.
    The items in <span style="color:red">red</span> are components
    that are either reduced or eliminated with LinuxBoot.
-   The dark <span style="color:blue">blue</span> items on the left
+   The <span style="color:blue">dark blue</span> items on the left
    cannot be changed.
 
 <img src="../images/Case-study-step1.svg" width=600px>
@@ -112,34 +112,34 @@ LinuxBoot provides a file system based on u-root standard
 utilities written in Go.
 
 Step 4. Through trial and error, continue to remove DXEs until you
-   can't remove anymore.
-
-   The DXEs are delivered as binary blobs. There are three ways
-    to handle them:
-
-   1. The most desirable is to remove them and let Linux drivers take
-      over what they did. This works well for USB, network, disk,
-      and other drivers, as well as network protocols and file
-      systems. In fact we have resolved many system reliability
-      and performance issues just by removing DXEs!
-
-   1. The second way is to replace the DXE with an open source driver.
-      This is less desirable, as the DXE environment is not as
-      hardened as the Linux kernel environment.
-   1. The final, least desired option, is to continue to use the DXE.
-      This is required if the DXE contains proprietary code that
-      "tweaks" chipset settings, for example, memory timing or
-      other controls, and there is no chance of ever bringing
-      them to open source.
+can't remove anymore.
+
+The DXEs are delivered as binary blobs. There are three ways
+ to handle them:
+
+1. The most desirable is to remove them and let Linux drivers take
+   over what they did. This works well for USB, network, disk,
+   and other drivers, as well as network protocols and file
+   systems. In fact we have resolved many system reliability
+   and performance issues just by removing DXEs!
+
+1. The second way is to replace the DXE with an open source driver.
+   This is less desirable, as the DXE environment is not as
+   hardened as the Linux kernel environment.
+1. The final, least desired option, is to continue to use the DXE.
+   This is required if the DXE contains proprietary code that
+   "tweaks" chipset settings, for example, memory timing or
+   other controls, and there is no chance of ever bringing
+   them to open source.
 
 <img src="../images/Case-study-step4.svg" width=600px>
 
 Step 5. Replace closed source DXEs with open source
 
 If we can build a DXE from source, we can use `utk` to:
 
-*  Remove the proprietary one
-*  Replace it with one built from source
+- Remove the proprietary one
+- Replace it with one built from source
 
 <img src="../images/Case-study-step5.svg" width=600px>
 
@@ -150,8 +150,11 @@ development continues to provide an open-source solution that
 does the following:
 
 1. Brings up the Linux kernel as a DXE in flash ROM instead of the UEFI shell.
-1. Provides a Go based userland that can then bring up the kernel that you want to run on the machine.
-1. Enables writing traditional firmware applications such as bootloader, debugging, diagnosis, and error detection applications as cross-architecture and cross-platform portable Linux applications.
+1. Provides a Go based userland that can then bring up the kernel that you want
+   to run on the machine.
+1. Enables writing traditional firmware applications such as bootloader,
+   debugging, diagnosis, and error detection applications as cross-architecture
+   and cross-platform portable Linux applications.
 
 The complete LinuxBoot solution is shown in the following diagram.
 

src/case_studies/TiogaPass.md

@@ -1,10 +1,19 @@
 # OCP TiogaPass Case Study
 
-Points of contact: [Jonathan Zhang](https://github.com/jonzhang-fb), [Andrea Barberio](https://github.com/insomniacslk), [David Hendricks](https://github.com/dhendrix), [Adi](https://github.com/agangidi53), [Morgan Jang](https://github.com/morganjangwiwynn), [Johnny Lin](https://github.com/johnnylinwiwynn)
-
-This case study describes information for firmware development community to use [OCP](https://www.opencompute.org/) platform TiogaPass, made by [Wiwynn Corporation](http://www.wiwynn.com/english).
+Points of contact:
+[Jonathan Zhang](https://github.com/jonzhang-fb),
+[Andrea Barberio](https://github.com/insomniacslk),
+[David Hendricks](https://github.com/dhendrix),
+[Adi](https://github.com/agangidi53),
+[Morgan Jang](https://github.com/morganjangwiwynn),
+[Johnny Lin](https://github.com/johnnylinwiwynn)
+
+This case study describes information for firmware development community to use
+[OCP](https://www.opencompute.org/) platform TiogaPass, made by [Wiwynn
+Corporation](http://www.wiwynn.com/english).
 
 It contains following sections:
+
 * [Quick Start](#Quick-Start)
 * [Details](#Details)
   * [How to build](#How-to-build)
@@ -18,72 +27,99 @@ It contains following sections:
 ## Quick Start
 
 * [Order the hardware](http://www.wiwynn.com/english) if you have not done so.
-* Download or build the firmware binary. The current solution is to boot embedded Linux kernel and initramfs as UEFI payload. Please contact Wiwynn to get a UEFI binary after ordering.
+* Download or build the firmware binary. The current solution is to boot
+  embedded Linux kernel and initramfs as UEFI payload. Please contact Wiwynn to
+  get a UEFI binary after ordering.
 * Flash the firmware.
   * Copy the downloaded firmware to OpenBMC.
   * From OpenBMC
-```
-  fw-util mb --update bios --force ./<firmware image name>
-```
+    ```
+      fw-util mb --update bios --force ./<firmware image name>
+    ```
 * Boot and enjoy.
   * From OpenBMC
-```
-  power-util mb reset
-  sol-util mb
-```
+    ```
+      power-util mb reset
+      sol-util mb
+    ```
 
 ## Details
+
 ### How to build
-Follow [Build Details](#Build-Details) for details on how to get the source code, and how to build.
 
-Boot flow of the current firmware solution is: Power on --> minimized UEFI --> Linuxboot --> target OS.
+Follow [Build Details](#Build-Details) for details on how to get the source
+code, and how to build.
+
+Boot flow of the current firmware solution is: Power on → minimized UEFI →
+Linuxboot → target OS.
+
+In near feature, the boot flow will be: power on → Coreboot → Linuxboot →
+target OS.
 
-In near feature, the boot flow will be: power on --> Coreboot --> Linuxboot --> target OS.
 #### Build Details
+
 * Download the code from [linuxboot github](https://github.com/linuxboot/linuxboot)
-```
-  git clone https://github.com/linuxboot/linuxboot.git
-```
+  ```
+    git clone https://github.com/linuxboot/linuxboot.git
+  ```
 * You need to apply Wiwiynn's linuxboot patch for now
-```
-cd linuxboot
-wget -O TiogaPass.patch https://github.com/johnnylinwiwynn/linuxboot/commit/28ae8450b3b05c6e6b8c74e29d0974ccf711d5e6.patch
-git am TiogaPass.patch
-```
-* Build the kernel bzImage (has embeded initramfs) for linuxboot, please reference
-  [Building u-root](https://github.com/linuxboot/book/tree/master/coreboot.u-root.systemboot#building-u-root) and
-  [Building a suitable Linux kernel](https://github.com/linuxboot/book/tree/master/coreboot.u-root.systemboot#building-a-suitable-linux-kernel)
-  for how to build the bzImage. You can always customize your Linux kernel configuration to suit your needs, please reference Wiwynn's kernel configuration file as a sample [linux_config](linux_config).
-* Place the tioga.rom into linuxboot/boards/tioga which is provided from Wiwynn after ordering, and also put your bzImage
-to the root folder of linuxboot, and then make
-```
-  cp path/to/tioga.rom linuxboot/boards/tioga
-  cp path/to/bzImage linuxboot
+  ```
   cd linuxboot
-  BOARD=tioga make
-```
+  wget -O TiogaPass.patch https://github.com/johnnylinwiwynn/linuxboot/commit/28ae8450b3b05c6e6b8c74e29d0974ccf711d5e6.patch
+  git am TiogaPass.patch
+  ```
+* Build the kernel bzImage (has embedded initramfs) for linuxboot, please
+  reference [Building u-root](https://github.com/linuxboot/book/tree/master/coreboot.u-root.systemboot#building-u-root)
+  and [Building a suitable Linux kernel](https://github.com/linuxboot/book/tree/master/coreboot.u-root.systemboot#building-a-suitable-linux-kernel)
+  for how to build the bzImage. You can always customize your Linux kernel
+  configuration to suit your needs, please reference Wiwynn's kernel
+  configuration file as a sample [linux_config](linux_config).
+* Place the tioga.rom into linuxboot/boards/tioga which is provided from Wiwynn
+  after ordering, and also put your bzImage to the root folder of linuxboot,
+  and then make
+  ```
+    cp path/to/tioga.rom linuxboot/boards/tioga
+    cp path/to/bzImage linuxboot
+    cd linuxboot
+    BOARD=tioga make
+  ```
 * You should see the built image at build/tioga/linuxboot.rom.
 
 ### How to operate
+
 Follow **TBD section** for details on:
-* How to flash. The image can be flashed either out-of-band, or from Linuxboot u-root shell, or from targetOS shell.
+
+* How to flash. The image can be flashed either out-of-band, or from Linuxboot
+  u-root shell, or from targetOS shell.
 * How to run Linuxboot u-root shell commands.
 
 ### Platform info
-The SKU contains TiogaPass board, a debug card, a VGA card, a power adapter. The details can be obtained from [Here](http://www.wiwynn.com/english).
 
-Platform design details (including the design spec and schematics) can be found from [Here](https://www.opencompute.org/products/108/wiwynn-tioga-pass-standard-sv7220g3-s-2u-ocp-server-up-to-768gb-8gb16gb32gb-ddr4-up-to-2666mts-12-dimm-slots).
+The SKU contains TiogaPass board, a debug card, a VGA card, a power adapter.
+The details can be obtained from the [Wiwynn Corporation](http://www.wiwynn.com/english).
+
+Platform design details (including the design spec and schematics) can be found
+on the [Open Compute Project UfiSpace product
+page](https://www.opencompute.org/products/108/wiwynn-tioga-pass-standard-sv7220g3-s-2u-ocp-server-up-to-768gb-8gb16gb32gb-ddr4-up-to-2666mts-12-dimm-slots).
 
 ## Support
+
 ### Hardware support
-Hardware support can be obtained from Wiwynn Corporation(http://www.wiwynn.com/english)
+
+Hardware support can be obtained from [Wiwynn Corporation](http://www.wiwynn.com/english).
 
 ### Community support
-[OCP Open System Firmware](https://www.opencompute.org/projects/open-system-firmware) is where industry collaborates on how to move forward with OSF. The OCP OSF project has regular recorded meetings and a mailing list.
 
-[Linuxboot open source community](https://www.linuxboot.org/) is the community you can ask any technical questions. Linuxboot community has a slack channel, a IRC channel, a mailing list and regular meetings.
+[OCP Open System Firmware](https://www.opencompute.org/projects/open-system-firmware)
+is where industry collaborates on how to move forward with OSF. The OCP OSF
+project has regular recorded meetings and a mailing list.
+
+[Linuxboot open source community](https://www.linuxboot.org/) is the community
+you can ask any technical questions. Linuxboot community has a slack channel, a
+IRC channel, a mailing list and regular meetings.
 
 ### Professional support
+
 Following companies provides professional support services:
 
 ** TBD **