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.schucha...@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