6 files changed, 198 insertions, 77 deletions
diff --git a/doc/board/starfive/deepcomputing_fml13v01.rst b/doc/board/starfive/deepcomputing_fml13v01.rst
new file mode 100644
index 00000000000..5d9612483b4
--- /dev/null
+++ b/doc/board/starfive/deepcomputing_fml13v01.rst
@@ -0,0 +1,80 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later
+
+DeepComputing Framework Motherboard (FLM13V01)
+==============================================
+
+The DeepComputing Framework motherboard (FLM13V01) can be combined with a
+13 inch Framework laptop chassis to provide a complete laptop.
+
+U-Boot for the board uses the same binaries as the VisionFive 2 board.
+Currently only serial console output is supported by mainline U-Boot.
+
+Building
+--------
+
+Setup the cross compilation environment variable:
+
+.. code-block:: bash
+
+   export CROSS_COMPILE=riscv64-linux-gnu-
+
+The M-mode software OpenSBI provides the supervisor binary interface (SBI) and
+is responsible for the switch to S-Mode. It is a prerequisite for building
+U-Boot. Support for the JH7110 was introduced in OpenSBI 1.2. It is recommended
+to use a current release.
+
+.. code-block:: bash
+
+    git clone https://github.com/riscv/opensbi.git
+    cd opensbi
+    make PLATFORM=generic FW_TEXT_START=0x40000000 FW_OPTIONS=0
+    export OPENSBI="$(pwd)/build/platform/generic/firmware/fw_dynamic.bin"
+
+Now build U-Boot SPL and main U-Boot.
+
+.. code-block:: bash
+
+    cd <U-Boot-dir>
+    make starfive_visionfive2_defconfig
+    make
+
+This will generate the U-Boot SPL image (spl/u-boot-spl.bin.normal.out) as well
+as the FIT image (u-boot.itb) with OpenSBI, U-Boot, and device-trees.
+
+Device-tree selection
+---------------------
+
+The product ID stored in the board EEPROM is used by U-Boot SPL to select the
+right configuration and device-tree from the u-boot.itb FIT image.
+
+Furthermore if variable $fdtfile has not been saved in the environment it is
+set based on the product ID to *starfive/jh7110-deepcomputing-fml13v01.dtb*.
+
+To overrule this default the variable can be set manually and saved in the
+environment
+
+.. code-block:: console
+
+    setenv fdtfile my_device-tree.dtb
+    env save
+
+Power switch
+------------
+
+A tiny power switch is located in right upper corner of the board.
+
+Open case detection
+-------------------
+
+The board has an open case detection switch. Red lights will flash and the
+board will not boot if the switch is not held down.
+
+UART
+----
+
+UART 0 is exposed via the side channel contacts SBU1 and SBU2 of the lower,
+right USB C connector. A USB C cable and a breakout board are needed for
+physical access. It depends on the cable orientation on which of SBU1 and SBU2
+you will find RX and TX. The signal voltage is 3.3 V. The baud rate is 115200.
+
+.. include:: jh7110_common.rst
diff --git a/doc/board/starfive/index.rst b/doc/board/starfive/index.rst
index 2cba1b6dc56..66abc6f9d98 100644
--- a/doc/board/starfive/index.rst
+++ b/doc/board/starfive/index.rst
@@ -6,6 +6,7 @@ StarFive
 .. toctree::
    :maxdepth: 1
 
+   deepcomputing_fml13v01
    milk-v_mars
    pine64_star64
    visionfive2
diff --git a/doc/board/starfive/jh7110_common.rst b/doc/board/starfive/jh7110_common.rst
new file mode 100644
index 00000000000..4a8058ee5da
--- /dev/null
+++ b/doc/board/starfive/jh7110_common.rst
@@ -0,0 +1,103 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later
+
+Boot source selection
+---------------------
+
+The board provides DIP switches to select the device for loading the boot
+firmware.
+
+=========== === ===
+Boot source SW1 SW2
+=========== === ===
+UART        OFF OFF
+SD-card     ON  OFF
+eMMC        OFF ON
+SPI flash   ON  ON
+=========== === ===
+
+Flashing a new U-Boot version
+-----------------------------
+
+U-Boot SPL is provided as file spl/u-boot-spl.bin.normal.out. Main U-Boot is
+in file u-boot.itb.
+
+Assuming your new U-Boot version is on partition 1 of an SD-card you could
+install it to the SPI flash with:
+
+.. code-block:: console
+
+    sf probe
+    load mmc 1:1 $kernel_addr_r u-boot-spl.bin.normal.out
+    sf update $kernel_addr_r 0 $filesize
+    load mmc 1:1 $kernel_addr_r u-boot.itb
+    sf update $kernel_addr_r 0x100000 $filesize
+
+For loading the files from a TFTP server refer to the dhcp and tftpboot
+commands.
+
+After updating U-Boot you may want to erase a saved environment and reboot.
+
+.. code-block:: console
+
+    env erase
+    reset
+
+Booting from SD-Card
+--------------------
+
+The device boot ROM loads U-Boot SPL (u-boot-spl.bin.normal.out) from the
+partition with type GUID 2E54B353-1271-4842-806F-E436D6AF6985. You are free
+to choose any partition number.
+
+With the default configuration U-Boot SPL loads the U-Boot FIT image
+(u-boot.itb) from partition 2 (CONFIG_SYS_MMCSD_RAW_MODE_U_BOOT_PARTITION=0x2).
+When formatting it is recommended to use GUID
+BC13C2FF-59E6-4262-A352-B275FD6F7172 for this partition.
+
+Booting from eMMC
+-----------------
+
+The device boot ROM tries to load U-Boot SPL (u-boot-spl.bin.normal.out) from
+sector 0 of the eMMC's main hardware partition. But this conflicts with GPT
+partitioning. Fortunately eMMC can alternatively load U-Boot SPL from a backup
+position.
+
+For U-Boot SPL (u-boot-spl.bin.normal.out) starting at sector 2048 (position
+0x100000) write the following bytes to the eMMC device after GPT partitioning:
+
+======= ========================
+Address Bytes
+======= ========================
+0x0000  40 02 00 00  00 00 10 00
+0x0290  40 02 00 00  00 00 10 00
+======= ========================
+
+With the default configuration U-Boot SPL loads the U-Boot FIT image
+(u-boot.itb) from partition 2 (CONFIG_SYS_MMCSD_RAW_MODE_U_BOOT_PARTITION=0x2).
+When formatting it is recommended to use GUID
+BC13C2FF-59E6-4262-A352-B275FD6F7172 for this partition.
+
+Booting from UART
+-----------------
+
+The boot ROM supports the X-modem protocol to upload
+spl/u-boot-spl.bin.normal.out. U-Boot SPL support loading the FIT image
+u-boot.itb via the Y-modem protocol.
+
+Due to restrictions of the boot ROM not all X-modem implementations are
+compatible. The package tio (https://github.com/tio/tio) has been found to be
+usable.
+
+Debug UART
+----------
+
+By default the SBI interface is used for the debug UART. But this only works
+in main U-Boot. To enable the debug UART in SPL, too, use the following
+settings::
+
+    CONFIG_DEBUG_UART=y
+    CONFIG_DEBUG_UART_NS16550=y
+    CONFIG_DEBUG_UART_BASE=0x10000000
+    CONFIG_SPL_DEBUG_UART_BASE=0x10000000
+    CONFIG_DEBUG_UART_CLOCK=24000000
+    CONFIG_DEBUG_UART_SHIFT=2
diff --git a/doc/board/starfive/milk-v_mars.rst b/doc/board/starfive/milk-v_mars.rst
index 554932ecfd4..ce4539a46f1 100644
--- a/doc/board/starfive/milk-v_mars.rst
+++ b/doc/board/starfive/milk-v_mars.rst
@@ -8,7 +8,7 @@ board. In U-Boot SPL the actual board is detected and the device-tree patched
 accordingly.
 
 Building
-~~~~~~~~
+--------
 
 1. Add the RISC-V toolchain to your PATH.
 2. Setup ARCH & cross compilation environment variable:
@@ -40,7 +40,7 @@ This will generate the U-Boot SPL image (spl/u-boot-spl.bin.normal.out) as well
 as the FIT image (u-boot.itb) with OpenSBI and U-Boot.
 
 Device-tree selection
-~~~~~~~~~~~~~~~~~~~~~
+---------------------
 
 Depending on the board version U-Boot set variable $fdtfile to either
 starfive/jh7110-starfive-visionfive-2-v1.2a.dtb or
@@ -57,15 +57,8 @@ environment
 or the configuration variable CONFIG_DEFAULT_FDT_FILE can be used to set to
 provide a default value.
 
-Boot source selection
-~~~~~~~~~~~~~~~~~~~~~
-
-The board provides the DIP switches MSEL[1:0] to select the boot device out of
-SPI flash, eMMC, SD-card, UART. To select booting from SD-card set the DIP
-switches MSEL[1:0] to 10.
-
 Preparing the SD-Card
-~~~~~~~~~~~~~~~~~~~~~
+---------------------
 
 The device firmware loads U-Boot SPL (u-boot-spl.bin.normal.out) from the
 partition with type GUID 2E54B353-1271-4842-806F-E436D6AF6985. You are free
@@ -105,7 +98,4 @@ Copy U-Boot to the SD card
 	sudo cp jh7110-starfive-visionfive-2.dtb /mnt/
 	sudo umount /mnt
 
-Booting
-~~~~~~~
-
-Once you plugin the sdcard and power up, you should see the U-Boot prompt.
+.. include:: jh7110_common.rst
diff --git a/doc/board/starfive/pine64_star64.rst b/doc/board/starfive/pine64_star64.rst
index 52e9a907917..d1752c452da 100644
--- a/doc/board/starfive/pine64_star64.rst
+++ b/doc/board/starfive/pine64_star64.rst
@@ -8,7 +8,7 @@ In U-Boot SPL the actual board is detected and the device-tree patched
 accordingly.
 
 Building
-~~~~~~~~
+--------
 
 1. Add the RISC-V toolchain to your PATH.
 2. Setup ARCH & cross compilation environment variable:
@@ -40,7 +40,7 @@ This will generate the U-Boot SPL image (spl/u-boot-spl.bin.normal.out) as well
 as the FIT image (u-boot.itb) with OpenSBI and U-Boot.
 
 Device-tree selection
-~~~~~~~~~~~~~~~~~~~~~
+---------------------
 
 U-Boot will set variable $fdtfile to starfive/jh7110-pine64-star64.dtb.
 
@@ -55,21 +55,8 @@ environment
 or the configuration variable CONFIG_DEFAULT_FDT_FILE can be used to set to
 provide a default value.
 
-Boot source selection
-~~~~~~~~~~~~~~~~~~~~~
-
-Boot mode is selected by an MSEL-DIP marked S1804 and GPIO_0 position adjacent
-to the 40pin GPIO header. ON/ONKE and number markings of the MSEL-DIP are
-misleading; Instead refer to the ``L`` (0) and ``H`` (1) silkscreen for
-accurate selection.
-
-+ (QSPI) Flash: 00
-+ SD: 01
-+ EMMC: 10
-+ UART: 11
-
 Preparing the SD-Card
-~~~~~~~~~~~~~~~~~~~~~
+---------------------
 
 The device firmware loads U-Boot SPL (u-boot-spl.bin.normal.out) from the
 partition with type GUID 2E54B353-1271-4842-806F-E436D6AF6985. You are free
@@ -109,13 +96,10 @@ Copy U-Boot to the SD card
 	sudo cp jh7110-starfive-visionfive-2.dtb /mnt/
 	sudo umount /mnt
 
-Booting
-~~~~~~~
-
-Once you plugin the sdcard and power up, you should see the U-Boot prompt.
+.. include:: jh7110_common.rst
 
 Serial Number and MAC address issues
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------------
 
 U-Boot requires valid EEPROM data to determine which board-specific fix-up to
 apply at runtime. This affects the size of memory initialized, network mac
diff --git a/doc/board/starfive/visionfive2.rst b/doc/board/starfive/visionfive2.rst
index 2c68df3ce4d..6f3c572f1f8 100644
--- a/doc/board/starfive/visionfive2.rst
+++ b/doc/board/starfive/visionfive2.rst
@@ -36,7 +36,7 @@ Currently, the u-boot.itb is used as a dynamic of the OpenSBI FW_DYNAMIC
 firmware with the latest.
 
 Building
-~~~~~~~~
+--------
 
 1. Add the RISC-V toolchain to your PATH.
 2. Setup ARCH & cross compilation environment variable:
@@ -72,7 +72,7 @@ This will generate the U-Boot SPL image (spl/u-boot-spl.bin.normal.out) as well
 as the FIT image (u-boot.itb) with OpenSBI and U-Boot.
 
 Device-tree selection
-~~~~~~~~~~~~~~~~~~~~~
+---------------------
 
 Depending on the board version U-Boot set variable $fdtfile to either
 starfive/jh7110-starfive-visionfive-2-v1.2a.dtb or
@@ -90,7 +90,7 @@ or the configuration variable CONFIG_DEFAULT_FDT_FILE can be used to provide
 a default value.
 
 Flashing
-~~~~~~~~
+--------
 
 The device firmware loads U-Boot SPL (u-boot-spl.bin.normal.out) from the
 partition with type GUID 2E54B353-1271-4842-806F-E436D6AF6985. You are free
@@ -132,16 +132,10 @@ Program the SD card
 	sudo cp jh7110-starfive-visionfive-2.dtb /mnt/
 	sudo umount /mnt
 
-Booting
-~~~~~~~
-
-The board provides the DIP switches MSEL[1:0] to select the boot device.
-To select booting from SD-card set the DIP switches MSEL[1:0] to 10.
-
-Once you plugin the sdcard and power up, you should see the U-Boot prompt.
+.. include:: jh7110_common.rst
 
 Sample boot log from StarFive VisionFive2 board
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------------------------
 
 .. code-block:: none
 
@@ -479,34 +473,3 @@ Sample boot log from StarFive VisionFive2 board
 
 	Welcome to Buildroot
 	buildroot login:
-
-Booting from SPI
-----------------
-
-Use Building steps from "Booting from MMC using U-Boot SPL" section.
-
-Partition the SPI in Linux via mtdblock. (Require to boot the board in
-SD boot mode by enabling MTD block in Linux)
-
-Use prebuilt image from here [1], which support to partition the SPI flash.
-
-
-Program the SPI (Require to boot the board in SD boot mode)
-
-Execute below steps on U-Boot proper,
-
-.. code-block:: none
-
-  sf probe
-  fatload mmc 1:3 $kernel_addr_r u-boot.itb
-  sf update $kernel_addr_r 0x100000 $filesize
-
-  fatload mmc 1:3 $kernel_addr_r u-boot-spl.bin.normal.out
-  sf update $kernel_addr_r 0x0 $filesize
-
-
-Power off the board
-
-Change DIP switches MSEL[1:0] are set to 00, select the boot mode to flash
-
-Power up the board.