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

Thu May 9 20:02:33 CEST 2024

Hi,

A couple of nits I missed. Good for PR otherwise.

On Thu, May 9, 2024 at 3:12 AM Heinrich Schuchardt
<heinrich.schuchardt at 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 at canonical.com>
> ---
> v3:
>         correct device-tree names
>         suggest not to use mac initialize
>         refer to XMODEM-1K
> 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 | 193 ++++++++++++++++++++++++++
>  2 files changed, 194 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

File extension is omitted for relative toctree references. See:
https://documatt.com/restructuredtext-reference/element/toctree.html:

"Relative document names are relative to the current document
(containing toctree). Relative document names are those which not
begin with /. For example, transition is transition.rst in the current
folder, or collection/parts is collection/parts.rst, etc."

'milk-v_mars.rst' should also drop the filename extension.

> 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..68561adadfc
> --- /dev/null
> +++ b/doc/board/starfive/milk-v_mars_cm.rst
> @@ -0,0 +1,193 @@
> +.. 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
> +
> +.. note::
> +
> +   The *mac initialize* command overwrites the vendor string and the MAC
> +   addresses. This is why it is avoided here.
> +
> +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.
> +
> +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.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
> +
> +::
> +
> +    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.
> +
> +The variable *$fdtfile* is used in the boot process to automatically load
> +a device-tree provided by the operating system. For details of the boot
> +process refer to the :doc:`U-Boot Standard Boot <../../../develop/bootstd>`
> +description.
> +
> +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 initiate 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 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.

Nit: This is correct but the word 'connected' is implied by
'disconnected' to be as
'connected in a disconnected state'. Delete the implied word 'connected':

"With nRPIBOOT disconnected from ground for SPI boot, power up the"

> --
> 2.43.0
>

Reviewed-by: E Shattow <lucent at gmail.com>