[v2,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>
---
v2:
	refer to tio as tool for booting via UART
	describe how to update serial number
	description updates as suggested by E. Shattow
---
 doc/board/starfive/index.rst          |   1 +
 doc/board/starfive/milk-v_mars_cm.rst | 183 ++++++++++++++++++++++++++
 2 files changed, 184 insertions(+)
 create mode 100644 doc/board/starfive/milk-v_mars_cm.rst

Hi, looking good to me except $fdtfile filename changes were missed to
match the code, and then testing inspires a few more things to
suggest.

On Fri, May 3, 2024 at 2:01 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>
> ---
> v2:
>         refer to tio as tool for booting via UART
>         describe how to update serial number
>         description updates as suggested by E. Shattow
> ---
>  doc/board/starfive/index.rst          |   1 +
>  doc/board/starfive/milk-v_mars_cm.rst | 183 ++++++++++++++++++++++++++
>  2 files changed, 184 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..d2be064d94c
> --- /dev/null
> +++ b/doc/board/starfive/milk-v_mars_cm.rst
> @@ -0,0 +1,183 @@
> +.. 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 and needs a different pin muxing
> +than the Milk-V Mars CM. The availability and size of the eMMC shows up in the
> +serial number displayed by the *mac* command, e.g.
> +MARC-V10-2340-D002E016-00000304. The number after the E is the MMC size. 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 if EEPROM data indicates eMMC is present
> +on the Milk-V Mars CM Lite. Otherwise you will not be able to read from the
> +SD-card.
> +
> +The serial number can be corrected using the *mac* command:
> +
> +.. code-block::
> +
> +    mac read_eeprom
> +    mac product_id MARC-V10-2340-D002E000-00000304
> +    mac write_eeprom
> +
> +By default the EEPROM is write protected. The write protection may be overcome
> +by connecting the "GND" and "EN" test pads on top of the module.

With adding boards based on VisionFive2 and having different vendor
info in EEPROM, the mac command should be extended for setting vendor
info from user input. Vendor info is currently not changeable back to
"MILK-V" after *mac initialize* sets vendor as  "StarFive Technology
Co., Ltd." If mac command can be extended then the documentation here
is sufficient, else some description warning the user not to *mac
initialize* on platforms other than VisionFive2 from StarFive.

> +
> +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_TEXT_START* is not needed anymore after OpenSBI patch d4d2582eef7a
> +"firmware: remove FW_TEXT_START" which should appear in OpenSBI 1.5.)
> +
> +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).

"Depending on the board version U-Boot sets variable $fdtfile to either
starfive/jh7110-milkv-mars-cm.dtb (with eMMC storage) or
starfive/jh7110-milkv-mars-cm-lite.dtb (without eMMC storage)."

> +
> +To overrule this selection the variable can be set manually and saved in the
> +environment
> +
> +::
> +
> +    setenv fdtfile my_device-tree.dtb
> +    env save

env set 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.

An additional hint will be helpful here for context of why $fdtfile is
set to a filename, i.e. "refer to X documentation for search path and
details on how $fdtfile affects the boot process." if/when
documentation exists.

> +
> +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.
> +
> +Compute module boards typically have a switch or jumper for this line.
> +
> +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:
> +
> +::
> +
> +    sf probe
> +    load mmc 0:1 $kernel_addr_r u-boot-spl.bin.normal.out
> +    sf update $kernel_addr_r 0 $filesize
> +    load mmc 0: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 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.
> +
> +With nRPIBOOT connected to ground for UART boot, power the board and 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. Tio is a terminal emulation that tolerates
> +these faults.
> +
> +::
> +
> +    $ tio -b 115200 --databits 8 --flow none --stopbits 1 /dev/ttyUSB0
> +    [08:14:54.700] tio v2.7
> +    [08:14:54.700] Press ctrl-t q to quit
> +    [08:14:54.701] Connected
> +
> +    (C)StarFive
> +    CCC
> +    (C)StarFive
> +    CCCCCCCC
> +
> +Press *ctrl-t x* to initate XMODEM transfer.

Correct spelling and include hint of which XMODEM variant mode to
choose in tio v2.8+ XMODEM upload menu:

"Press *ctrl-t x* to initiate XMODEM (XMODEM-1K) transfer."

> +
> +::
> +
> +    [08:15:14.778] Send file with XMODEM
> +    [08:15:22.459] Sending file 'u-boot-spl.bin.normal.out'
> +    [08:15:22.459] Press any key to abort transfer
> +    ........................................................................
> +    .......................................................................|
> +    [08:15:22.459] Done
> +
> +    U-Boot SPL 2024.07-rc1-00075-gd6a4ab20097 (Apr 25 2024 - 16:32:10 +0200)
> +    DDR version: dc2e84f0.
> +    Trying to boot from UART
> +    CC
> +
> +Press *ctrl-t y* to initate YMODEM transfer.

Correct spelling:

"Press *ctrl-t y* to initiate YMODEM transfer."

> +
> +::
> +
> +    [08:15:50.331] Send file with YMODEM
> +    [08:15:53.540] Sending file 'u-boot.itb'
> +    [08:15:53.540] Press any key to abort transfer
> +    ........................................................................
> +    …
> +    ...............|
> +    [08:15:53.540] Done
> +    Loaded 1040599 bytes
> +
> +
> +    U-Boot 2024.07-rc1-00075-gd6a4ab20097 (Apr 25 2024 - 16:32:10 +0200)
> +
> +Booting from SPI flash
> +~~~~~~~~~~~~~~~~~~~~~~
> +
> +With nRPIBOOT connected disconnected from ground for SPI boot, power up the
> +board. You should see the U-Boot prompt on the serial console.
> --
> 2.43.0
>

-E