[PATCH 3/4] doc: Milk-V Mars CM and Milk-V Mars CM Lite

[Heinrich Schuchardt]

Provide a man-page describing the usage of U-Boot on
the Milk-V Mars CM and Milk-V Mars CM Lite boards.

Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt at canonical.com>
---
 doc/board/starfive/index.rst          |   1 +
 doc/board/starfive/milk-v_mars_cm.rst | 125 ++++++++++++++++++++++++++
 2 files changed, 126 insertions(+)
 create mode 100644 doc/board/starfive/milk-v_mars_cm.rst

diff --git a/doc/board/starfive/index.rst b/doc/board/starfive/index.rst
index 2762bf74c11..afa85ad2540 100644
--- a/doc/board/starfive/index.rst
+++ b/doc/board/starfive/index.rst
@@ -7,4 +7,5 @@ StarFive
    :maxdepth: 1
 
    milk-v_mars.rst
+   milk-v_mars_cm.rst
    visionfive2
diff --git a/doc/board/starfive/milk-v_mars_cm.rst b/doc/board/starfive/milk-v_mars_cm.rst
new file mode 100644
index 00000000000..4cd6034281c
--- /dev/null
+++ b/doc/board/starfive/milk-v_mars_cm.rst
@@ -0,0 +1,125 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Milk-V Mars CM
+==============
+
+U-Boot for the Milk-V Mars CM uses the same U-Boot binaries as the VisionFive 2
+board. In U-Boot SPL the actual board is detected and the device-tree patched
+accordingly.
+
+The Milk-V Mars CM Lite comes without eMMC it needs a different pin muxing.
+The size of the eMMC shows up in the serial number shown by the *mac* command,
+e.g. MARC-V10-2340-D002E016-00000304. The number after the E is the MMC size
+in GB. U-Boot takes a value of E000 as an indicator for the Lite version.
+Unfortunately the vendor has not set this value correctly on some Lite boards.
+Please, use CONFIG_STARFIVE_NO_EMMC=y to indicate a Milk-V Mars CM Lite in this
+case. Otherwise you will not be able to read from eMMC
+
+Building
+~~~~~~~~
+
+1. Add the RISC-V toolchain to your PATH.
+2. Setup ARCH & cross compilation environment variable:
+
+.. code-block:: none
+
+   export CROSS_COMPILE=<riscv64 toolchain prefix>
+
+The M-mode software OpenSBI provides the supervisor binary interface (SBI) and
+is responsible for the switch to S-Mode. It is a prerequisite to build U-Boot.
+Support for the JH7110 was introduced in OpenSBI 1.2. It is recommended to use
+a current release.
+
+.. code-block:: console
+
+	git clone https://github.com/riscv/opensbi.git
+	cd opensbi
+	make PLATFORM=generic FW_TEXT_START=0x40000000 FW_OPTIONS=0
+
+Now build the U-Boot SPL and U-Boot proper.
+
+.. code-block:: console
+
+	cd <U-Boot-dir>
+	make starfive_visionfive2_defconfig
+	make OPENSBI=$(opensbi_dir)/build/platform/generic/firmware/fw_dynamic.bin
+
+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 sets variable $fdtfile to either
+starfive/jh7110-milkv-mars-cm-emmc.dtb (for the generic version or
+starfive/jh7110-milkv-mars-cm-sdcard.dtb (for the Lite version).
+
+To overrule this selection the variable can be set manually and saved in the
+environment
+
+::
+
+    setenv fdtfile my_device-tree.dtb
+    env save
+
+or the configuration variable CONFIG_DEFAULT_FDT_FILE can be used to set to
+provide a default value.
+
+Boot source selection
+~~~~~~~~~~~~~~~~~~~~~
+
+The low speed connector nRPIBOOT line is used to switch the boot source.
+
+* If nRPIBOOT is connected to ground, the board boots from UART.
+* If nRPIBOOT is not connected, the board boots from SPI flash.
+
+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 to the SPI flash with:
+
+::
+
+    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
+
+After updating U-Boot you may want to reboot and reset the environment to the
+default.
+
+::
+
+    env default -f -a
+    env save
+
+Booting from UART
+~~~~~~~~~~~~~~~~~
+
+For booting via UART U-Boot must be built with CONFIG_SPL_YMODEM_SUPPORT=y.
+
+Upload u-boot-spl.bin.normal.out via XMODEM. Then upload u-boot.itb via
+YMODEM.
+
+The XMODEM implementation in the boot ROM is not fully specification compliant.
+It sends too many NAKs in a row. Some tolerant terminal implementations exist.
+Or use a dedicated recovery tool e.g.
+https://github.com/xypron/JH71xx-tools/tree/VisionFive2:
+
+.. code-block:: bash
+
+    # send U-Boot SPL via XMODEM
+    vf2-recover -D /dev/ttyUSB0 -r u-boot-spl.bin.normal.out
+    # connect to board to transfer main U-Boot via YMODEM
+    picocom --send-cmd 'sz -b -vv' --baud 115200 /dev/ttyUSB0
+    # In Picocom use <CTRL+A>,<CTRL+S> to send u-boot.itb
+
+Booting from SPI flash
+~~~~~~~~~~~~~~~~~~~~~~
+
+Once you power up, you should see the U-Boot prompt on the serial console.
-- 
2.43.0