docs/unified/protectli: Reorganize protectli docs

Co-authored-by: Jan Prusinowski <jan.prusinowski@3mdeb.com> Co-authored-by: Michał Żygowski <michal.zygowski@3mdeb.com> Co-authored-by: Filip Lewiński <filip.lewinski@3mdeb.com> Signed-off-by: Filip Gołaś <filip.golas@3mdeb.com>
Dasharo · Sep 16, 2024 · 514e8d2 · 514e8d2
1 parent 940cb4e
commit 514e8d2
Show file tree

Hide file tree

Showing 50 changed files with 1,736 additions and 2,130 deletions.
diff --git a/docs/guides/lab-assembly/protectli.md b/docs/guides/lab-assembly/protectli.md
@@ -3,7 +3,7 @@
 ## Introduction
 
 This document describes platform-specific details for assembling Protectli
-VP2410, VP2420, VP4630/VP4650/VP4670, V1210/V1410/V1610, VP66xx testing stands.
+VP2410, VP2420, VP4630/VP4650/VP4670, V1000 series testing stands.
 Use this document as reference while going through
 [Generic Testing Stand Setup](../../unified-test-documentation/generic-testing-stand-setup.md)
 
@@ -45,9 +45,9 @@ connect ports 3 and 4 together with an additional RJ45 cable.
         - VP4630: 12V 5A
         - VP4650/VP4670: 12V 7.5A
 
-=== "V1X10"
+=== "V1000 series"
 
-    * V1X10 platform
+    * V1000 series platform
     * Power supply for the platform: 12V 4A
     * USB-C to USB-A male-male cable for console
 
@@ -79,7 +79,7 @@ connect ports 3 and 4 together with an additional RJ45 cable.
     Flash chip is socketed. One has to desolder the socket, solder the flash
     chip in place of the socket and connect the Pomona SOIC8 clip.
 
-=== "V1X10"
+=== "V1000 series"
 
     Connect the RTE SPI header to the platform using the 2.54mm female-female
     wires as described in the table:
@@ -147,7 +147,7 @@ connect ports 3 and 4 together with an additional RJ45 cable.
 
     Resetting CMOS is required for proper external flashing.
 
-=== "V1X10"
+=== "V1000 series"
 
     Connect the RTE J11 header to the platform CLR_CMOS1 header using 2.54mm to 2mm
     wires as described in the table:
@@ -237,7 +237,7 @@ The method of setting and using serial connection is described in the
         osfv_cli sonoff --sonoff_ip <sonoff_ip_address> off
         ```
 
-=== "V1X10"
+=== "V1000 series"
 
     Power supply controlling is performed with the relay module on RTE
     connected to one of RTE GPIOs. Power operation should be performed using

diff --git a/docs/newcomers.md b/docs/newcomers.md
@@ -197,7 +197,7 @@ Check if Sonoff state is set to ON `osfv_cli sonoff --sonoff_ip
 
 **Ubuntu won't download and create image**
 
-1. Download image from: [Ubuntu](https://ubuntu.task.gda.pl/ubuntu-releases/22.04.4/ubuntu-22.04.4-desktop-amd64.iso),
+1. Download image from: [Ubuntu](https://ubuntu.task.gda.pl/ubuntu-releases/22.04.4/ubuntu-22.04.5-desktop-amd64.iso),
 and use the script:
 
 ```./ubuntu/create_image.sh -i ~/Downloads/ubuntu-22.04.4-desktop-amd64.iso```
diff --git a/docs/unified/protectli/building-manual.md b/docs/unified/protectli/building-manual.md
@@ -0,0 +1,268 @@
+# Building manual
+
+## Intro
+
+This document describes the procedure for building coreboot for all Protectli
+devices.
+
+## Requirements
+
+- Docker
+    + follow [Install Docker Engine on Ubuntu](https://docs.docker.com/engine/install/ubuntu/)
+    + follow [Post-installation steps for Linux](https://docs.docker.com/engine/install/linux-postinstall/)
+- Git
+    + `sudo apt-get install git`
+
+## Building
+
+To build Dasharo firmware image, first clone the coreboot repository:
+    ```bash
+    git clone https://github.com/Dasharo/coreboot.git
+    ```
+then follow the steps below:
+
+=== "fw6"
+
+    1. Checkout to the device's branch:
+        ```bash
+        cd coreboot
+        git checkout protectli_vault_kbl/release
+        ```
+
+    To build a specific version replace `protectli_vault_kbl/release` to
+    `protectli_vault_kbl_v1.0.x` where `x` is the version number.
+
+    2. Start build process (note it requires certain blobs to proceed):
+
+        ```bash
+        cd coreboot
+        git submodule update --init --checkout
+        # you will need to obtain the ZIP with blobs at this point
+        unzip protectli_blobs.zip -d 3rdparty/blobs/mainboard
+        ./build.sh fw6
+        ```
+
+=== "v1000-series"
+
+    1. Checkout the desired version, e.g. `v0.9.3`:
+
+        ```bash
+        cd coreboot
+        git checkout protectli_vault_jsl_v0.9.3
+        ```
+
+    2. Checkout submodules:
+
+        ```bash
+        git submodule update --init --checkout
+        ```
+
+    3. Obtain the Protectli blobs package (only for versions v0.9.0 and v0.9.1):
+
+        > Replace `<PROTECTLI_BLOBS_REPO>` with a a proper path to the repository
+        > in a form of: `git@repo-path.git`. You should checkout to the same tag as
+        > in case of the coreboot repository.
+
+        ```bash
+        cd 3rdparty/blobs/mainboard/
+        git init
+        git remote add origin <PROTECTLI_BLOBS_REPO>
+        git fetch origin && git checkout protectli_vault_jsl_v0.9.0
+        cd -
+        ```
+
+    4. Build the firmware:
+
+        + for V1210
+
+            ```bash
+            ./build.sh V1210
+            ```
+
+        + for V1211
+
+            ```bash
+            ./build.sh V1211
+            ```
+
+        + for V1410
+
+            ```bash
+            ./build.sh V1410
+            ```
+
+        + for V1610
+
+            ```bash
+            ./build.sh V1610
+            ```
+
+    The resulting coreboot image will be placed in the coreboot directory as
+    `protectli_V1210.rom`, `protectli_V1410.rom` or `protectli_V1610.rom`
+    respectvely.
+
+=== "vp46xx"
+
+    Since version v1.0.18 VP4630 and VP4650 use different configuration file than
+    VP4670. Versions v1.0.17 and older do not support VP4650 and VP4670 at all.
+
+    Versions v1.1.1 and newer support all variants with a single binary.
+
+    1. Checkout the desired version, e.g. `v1.1.0`:
+
+        ```bash
+        cd coreboot
+        git checkout protectli_vault_cml_v1.1.0
+        ```
+
+    2. Checkout submodules:
+
+        ```bash
+        git submodule update --init --checkout
+        ```
+
+    3. Obtain the Protectli blobs package (only for version v1.1.0 and older):
+
+        > Replace `<PROTECTLI_BLOBS_REPO>` with a a proper path to the repository
+        > in a form of: `git@repo-path.git`. You should checkout to the same tag as
+        > in case of the coreboot repository.
+
+        ```bash
+        cd 3rdparty/blobs/mainboard/
+        git init
+        git remote add origin <PROTECTLI_BLOBS_REPO>
+        git fetch origin && git checkout protectli_vault_cml_v1.1.0
+        cd -
+        ```
+
+    4. Build the firmware:
+
+        === "v1.1.1 or newer"
+
+            ```bash
+            ./build.sh vp46xx
+            ```
+
+            The resulting coreboot image will be placed in the coreboot directory as
+            `protectli_vault_cml_<version>_vp46xx.rom`.
+
+        === "V1.1.0 or older"
+
+            === "VP4630 and VP4650"
+
+                ```bash
+                ./build.sh vp4630_vp4650
+                ```
+
+                The resulting coreboot image will be placed in the coreboot
+                directory as `protectli_vault_cml_<version>_vp4630_vp4650.rom`.
+
+            === "VP4670"
+
+                ```bash
+                ./build.sh vp4670
+                ```
+
+                The resulting coreboot image will be placed in the coreboot
+                directory as `protectli_vault_cml_<version>_vp4670.rom`.
+
+=== "vp66xx"
+
+    1. Checkout the desired version, e.g. `v0.9.0`:
+
+        ```bash
+        cd coreboot
+        git checkout protectli_vault_adl_v0.9.0
+        ```
+
+    2. Checkout submodules:
+
+        ```bash
+        git submodule update --init --checkout
+        ```
+
+    3. Build the firmware:
+
+        ```bash
+        ./build.sh vp66xx
+        ```
+
+    The resulting coreboot image will be placed in the coreboot directory as
+    `protectli_vp66xx.rom`.
+
+=== "vp2410"
+
+    1. Checkout the desired version, e.g. `v1.0.15`:
+
+        ```bash
+        cd coreboot
+        git checkout protectli_vault_glk_v1.0.15
+        ```
+
+    2. Checkout submodules:
+
+        ```bash
+        git submodule update --init --checkout
+        ```
+
+    3. Obtain the Protectli blobs package (only for v1.0.15 or older):
+
+        > Replace `<PROTECTLI_BLOBS_REPO>` with a a proper path to the repository
+        > in a form of: `git@repo-path.git`. You should checkout to the same tag as
+        > in case of the coreboot repository.
+
+        ```bash
+        cd 3rdparty/blobs/mainboard/
+        git init
+        git remote add origin <PROTECTLI_BLOBS_REPO>
+        git fetch origin && git checkout protectli_vault_glk_v1.0.15
+        cd -
+        ln -s ../blobs/mainboard/protectli/vault_glk/GeminilakeFspBinPkg/ 3rdparty/fsp/GeminilakeFspBinPkg
+        ```
+
+    4. Build the firmware:
+
+        ```bash
+        ./build.sh vp2410
+        ```
+
+    The resulting coreboot image will be placed in the coreboot directory as
+    `protectli_vp2410_<version>.rom`.
+
+=== "vp2420"
+
+    1. Checkout the desired version, e.g. `v1.1.0`:
+
+        ```bash
+        cd coreboot
+        git checkout protectli_vault_ehl_v1.1.0
+        ```
+
+    2. Checkout submodules:
+
+        ```bash
+        git submodule update --init --checkout
+        ```
+
+    3. Obtain the Protectli blobs package (only v1.1.0 or older):
+
+        > Replace `<PROTECTLI_BLOBS_REPO>` with a a proper path to the repository
+        > in a form of: `git@repo-path.git`. You should checkout to the same tag as
+        > in case of the coreboot repository.
+
+        ```bash
+        cd 3rdparty/blobs/mainboard/
+        git init
+        git remote add origin <PROTECTLI_BLOBS_REPO>
+        git fetch origin && git checkout protectli_vault_ehl_v1.1.0
+        cd -
+        ```
+
+    4. Build the firmware:
+
+        ```bash
+        ./build.sh vp2420
+        ```
+
+    The resulting coreboot image will be placed in the coreboot directory as
+    `protectli_vp2420_<version>.rom`.