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

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

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.git
> +       cd opensbi
> +       make 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_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

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
>