Merge pull request #457 from Dasharo/supermicro_x11_lga1151_series/docs-v0.0.2

supermicro_x11_lga1151_series: extend initial deployment and recovery…

docs/dasharo-tools-suite/documentation.md

@@ -247,6 +247,73 @@ ethernet cable. More information can be found in
 
 ![](./images/dts-hcl-run.png)
 
+#### HCL Report correctness
+
+Please note DTS HCL Report assumes that your chipset is already supported by
+flashrom. There are also other false negative errors and unknowns, which we
+trying to fix to improve user experience.
+
+Always check `results` file to confirm quality of your HCL report. Sample
+content of such file may look as follows:
+
+```text
+[OK]    PCI configuration space and topology
+[UNKNOWN] USB devices and topology
+[OK]    Super I/O configuration
+[UNKNOWN] EC configuration
+[ERROR]   MSRs
+[OK]    SMBIOS tables
+[OK]    BIOS information
+[OK]    CMOS NVRAM
+[UNKNOWN] Intel configuration registers
+[OK]    GPIO configuration C header files
+[OK]    kernel dmesg
+[OK]    ACPI tables
+[UNKNOWN] Audio devices configuration
+[OK]    CPU info
+[OK]    I/O ports
+[OK]    Input bus types
+[OK]    Firmware image
+[OK]    I2C bus
+[UNKNOWN] ACPI tables
+[OK]    Touchpad information
+[OK]    DIMMs information
+[ERROR]   CBMEM table information
+[ERROR]   TPM information
+[ERROR]   AMT information
+[OK]    ME information
+Results of getting data:
+
+Legend:
+[OK]     Data get successfully
+[UNKNOWN]  Result is unknown
+[ERROR]    Error during getting data
+```
+
+Please report all errors exerienced while performing dump to
+[dasharo-issues](https://github.com/Dasharo/dasharo-issues) repository.
+
+#### BIOS backup
+
+One of the key components of HCL Report is your BIOS backup. To prepare BIOS
+backup of your platform simply run HCL Report and decide if you would like to
+contribute information about your hardware configuration.
+
+Please consider following options depending on your situation:
+
+* **YES** - If you decided to contribute you can always [get back to
+  us](https://www.dasharo.com/pages/contact/) and ask about BIOS backup, which
+  we will provide after simple verification that you are the owner of the
+  hardware.
+* **NO (default)** - If you decided to not contribute your situation depends on
+  boot method you used to execute DTS:
+    - **Network Boot** - please note that Dasharo booted over iPXE assumes no storage
+      available, so report and your BIOS backup are stored in temporary memory
+      and will not be available after reboot. Please make sure to move HCL report
+      to not volatile storage. This can be done using option `9) Shell`
+    - **USB Boot** - HCL report and BIOS backup are saved to USB storage root
+      directory.
+
 ### Firmware update
 
 Within DTS, you may use the `flashrom` and `fwupdmgr` utilities to update,

docs/variants/supermicro_x11_lga1151_series/initial-deployment.md

@@ -4,6 +4,31 @@ Initial deployment for Supermicro X11SSH is supported in DTS since version
 [vTBD](#tbd). Please check [Dasharo zero-touch initial deployment
 section](../../dasharo-tools-suite/documentation.md#dasharo-zero-touch-initial-deployment).
 
+We strongly recommend following these official instructions. The official guide
+has a lot of collaborative effort put into covering all of the edge cases and
+is regularly tested. Following these instructions to the letter without
+skipping, reordering or adding any steps will give you a proper Dasharo
+installation unless there's a hardware issue.  We strongly recommend against
+following unofficial guides deviating in any way from the official
+instructions.
+
+If you have trouble with the installation process, ask for help on the official
+[Dasharo chat channel](../../../#community). There are almost always people
+around willing to help with it. Before asking for help, make an attempt to
+follow the guide on your own and then ask for help with anything you get stuck
+on.
+
+## Hardware preparation
+
+Please use Supermicro Quick Reference Guide for you mainboard e.g.
+[X11SSH-TF](https://www.supermicro.com/QuickRefs/motherboard/C236/QRG-1783.pdf).
+Find JPME2 and change its state to position 2-3, which means ME Manufacturing
+Mode enabled.
+
+<center>
+![](../../images/x11_mfg_mode.jpg)
+</center>
+
 ## Booting DTS over network
 
 For seamless and storageless deployment one can use BMC virtual floppy
@@ -50,6 +75,11 @@ OS installation (netboot.xyz official server)
 iPXE Shell
 ```
 
+## Vendor BIOS backup
+
+Please follow [DTS backup
+guide](../../../dasharo-tools-suite/documentation/#bios-backup).
+
 ## Installing Dasharo with DTS
 
 TBD

docs/variants/supermicro_x11_lga1151_series/recovery.md

@@ -24,7 +24,8 @@ Update](../firmawre-update).
 
 Without active license you can't use BIOS Update feature. License key can be
 generated using [kasuganosoras
-scripts](https://github.com/kasuganosoras/SuperMicro-IPMI-LicenseGenerator).
+scripts](https://github.com/kasuganosoras/SuperMicro-IPMI-LicenseGenerator) and
+entered through BMC web interface (`Miscellaneous->Activate License`).
 
 #### Up to date firmware
 
@@ -36,3 +37,14 @@ Please make sure you using firmware revision 01.60
 If not please follow `IPMI Firmware Update_NEW.pdf` instruction from package
 that you can download
 [here](https://www.supermicro.com/en/support/resources/downloadcenter/firmware/MBD-X11SSH-TF/BMC).
+
+Unfortunately most efficient way to interact with proprietary BMC is to use
+Supermicro proprietary closed source tools:
+
+* [Supermicro Update
+  Manager](https://www.supermicro.com/en/solutions/management-software/supermicro-update-manager)
+   please download and unpack archive.
+* [Backup](../../../dasharo-tools-suite/documentation/#bios-backup) or
+  [Supermicro BIOS
+  update](https://www.supermicro.com/en/support/resources/downloadcenter/firmware/MBD-X11SSH-TF/BIOS)
+   please download and unpack archive.