On Mon, Apr 15, 2024 at 4:50 AM Heinrich Schuchardt heinrich.schuchardt@canonical.com wrote:
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@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.
JH7110 Technical Reference Manual does list some sdio related mux function with this GPIO62/GPIO22 substitution. I did not hear back yet from Milk-V developer support per my request for clarifying why this is needed and relevant schematics. I want this explained more clearly in documentation the purpose for this different pin muxing or why it is needed in the U-Boot phase of the boot process for specifically Milk-V Mars CM Lite (SD Card non-eMMC version). Previously I thought it was something about the power regulator not having a complete device driver in U-Boot but I don't know. Is it a bodge or is it intentional for easier manufacture?
+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
The number may have 'T' suffix making this description wrong. Describing as unit-less "size." is enough, so delete "in GB."
+in GB. U-Boot takes a value of E000 as an indicator for the Lite version.
None of the Lite versions have eMMC so that can be inferred without naming the specific product. Maybe in future there is some other need for this config option so keep it generic.
Suggest "U-Boot takes a value of E000 as an indicator for not having an eMMC."
+Unfortunately the vendor has not set this value correctly on some Lite boards.
Milk-V developer support acknowledged 14th Apr 2024 my e-mail inquiry about wrong EEPROM data, but did not comment (yet) on instructions for a fix for boards that have wrong EEPROM data.
As for documentation we should have something that describes how to confirm the data is correct and if it is not then what can be done, in the case of fixing the EEPROM data and not.
Suggest to add: "In default operation EEPROM Write Protect is enabled, and may be disabled connecting the "GND" and "EN" test pads on top of the module."
and an example of `mac product_id` also `mac write_eeprom` commands. You can do this with a steady hand and a paperclip, as the pads are accessible near the board edge even with the heatsink in place. Lest we be blamed for bad decisions users make with a paperclip though, I don't know if you want to include this information. I think it was easy to do and future production runs should have the correct EEPROM data value for eMMC so it would make sense to want to update this.
+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
Suggest: "Please, use CONFIG_STARFIVE_NO_EMMC=y when EEPROM data indicates eMMC is present on Milk-V Mars CM Lite. Otherwise you will not be able to read from SD Card."
+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.gitcd opensbimake PLATFORM=generic FW_TEXT_START=0x40000000 FW_OPTIONS=0
Is it needed to pass FW_OPTIONS ?
FW_TEXT_START is deprecated in opensbi commit d4d2582e (8th Apr 2024). Keep for compatibility but noted here in review.
+Now build the U-Boot SPL and U-Boot proper.
+.. code-block:: console
cd <U-Boot-dir>make starfive_visionfive2_defconfigmake 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
In my testing of Mars CM Lite the SD-Card appears as mmc 0:1 and not mmc 1:1. If you had eMMC that would be mmc 1:1, I guess, but I don't have the Mars CM with eMMC version here to confirm. That description could be changed to refer to eMMC, and/or example reflecting SD Card. How is this on the Mars, is there both SD and eMMC?
- sf update $kernel_addr_r 0x100000 $filesize
I have been using $loadaddr for memory address with spi flash procedure as less typing and easier to remember than $kernel_addr_r ; Is there a reason or U-Boot convention for one or the other?
+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.
Prefix the following to reference the earlier explanation: "With nRPIBOOT set for UART boot, power the board and upload..."
+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
Comment: I've been using 'tio' serial tool that has its own XMODEM and YMODEM implementation not depending on 'sz'. Would like to see this as an additional mention for an all-in-one tool if you can confirm that it does not hit the JH7110 XMODEM implementation bug - I'm not sure, but I have had success with it so I think it's okay. 'tio' is widely available in Linux distros so that may be more convenient for users, unless it does hit that bug and I haven't noticed it, I just tried a lot of tools until finding that this seems to work for me.
+Booting from SPI flash +~~~~~~~~~~~~~~~~~~~~~~
+Once you power up, you should see the U-Boot prompt on the serial console.
2.43.0