[2/2,v2] board: starfive: support Pine64 Star64 board

Add documentation files

Signed-off-by: Henry Bell <dmoo_dv@protonmail.com>
Cc: ycliang@andestech.com
Cc: heinrich.schuchardt@canonical.com
---

Changes since v1

- New patch
---
 doc/board/starfive/index.rst         |   1 +
 doc/board/starfive/pine64_star64.rst | 109 +++++++++++++++++++++++++++
 2 files changed, 110 insertions(+)
 create mode 100644 doc/board/starfive/pine64_star64.rst

On Wed, May 8, 2024 at 10:15 PM H Bell <dmoo_dv@protonmail.com> wrote:
>
>
> Add documentation files
>
> Signed-off-by: Henry Bell <dmoo_dv@protonmail.com>
> Cc: ycliang@andestech.com
> Cc: heinrich.schuchardt@canonical.com
> ---
>
> Changes since v1
>
> - New patch
> ---
>  doc/board/starfive/index.rst         |   1 +
>  doc/board/starfive/pine64_star64.rst | 109 +++++++++++++++++++++++++++
>  2 files changed, 110 insertions(+)
>  create mode 100644 doc/board/starfive/pine64_star64.rst
>
> diff --git a/doc/board/starfive/index.rst b/doc/board/starfive/index.rst
> index 2762bf74c1..f05f8a0765 100644
> --- a/doc/board/starfive/index.rst
> +++ b/doc/board/starfive/index.rst
> @@ -7,4 +7,5 @@ StarFive
>     :maxdepth: 1
>
>     milk-v_mars.rst
> +   pine64_star64
>     visionfive2

Ack. FYI series 406254 "board: starfive: add Milk-V Mars CM support"
corrects the milk-v_mars.rst listing in index.rst

> diff --git a/doc/board/starfive/pine64_star64.rst b/doc/board/starfive/pine64_star64.rst
> new file mode 100644
> index 0000000000..047f109028
> --- /dev/null
> +++ b/doc/board/starfive/pine64_star64.rst
> @@ -0,0 +1,109 @@
> +.. SPDX-License-Identifier: GPL-2.0+
> +
> +Pine64 Star64
> +===========
> +
> +U-Boot for the Star64 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.
> +
> +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
> +

Delete FW_OPTIONS. Keep FW_TEXT_START for compatibility.

FW_OPTIONS=0 is no-op and FW_TEXT_START is deprecated as of OpenSBI
commit d4d2582e (assume ~6mo release schedule 1.5 could be expected 6-7wks).

> +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
> +~~~~~~~~~~~~~~~~~~~~~
> +
> +U-Boot will set variable $fdtfile to starfive/jh7110-pine64-star64.dtb.
> +
> +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 board provides the DIP switches MSEL[1:0] to select the boot device out of
> +SPI flash, eMMC, SD-card, UART. To select booting from SD-card set the DIP
> +switches MSEL[1:0] to 10.
> +

Seems unclear to me looking at a picture of the board and reading this
description.

From the Pine64 Wiki page about Star64:
""
Booting from uSD: Component S1804 is adjacent to the 40pin GPIO Bus;
ignore the printed text on S1804 that says "ON" or "ONKE". Do pay
attention to the '1' and '2' printed on S1804. Also pay attention to
the 'L' and 'H' text on the board next to S1804. The 'L' stand for '0'
and the 'H' stands for '1'. You will need to flip switch '1' (GPIO_1)
on S1804 to the 'L' position and switch '2' (GPIO_0) on S1804 to the
'H' position. S1804 maps to the table next to S1804 that has text [
[GPIO_1 | GPIO_0], [0|0] Flash, [0|1] SD, [1|0] EMMC, [1|1] UART ];
""

So the table silkscreen on the board is correct, and in the table 0=L 1=H ?

Also the JH7110 TRM from StarFive officially cautions that booting
from SD is not reliable.

> +Preparing the SD-Card
> +~~~~~~~~~~~~~~~~~~~~~
> +
> +The device firmware loads U-Boot SPL (u-boot-spl.bin.normal.out) from the
> +partition with type GUID 2E54B353-1271-4842-806F-E436D6AF6985. You are free
> +to choose any partition number.
> +
> +With the default configuration U-Boot SPL loads the U-Boot FIT image
> +(u-boot.itb) from partition 2 (CONFIG_SYS_MMCSD_RAW_MODE_U_BOOT_PARTITION=0x2).
> +When formatting it is recommended to use GUID
> +BC13C2FF-59E6-4262-A352-B275FD6F7172 for this partition.
> +
> +The FIT image (u-boot.itb) is a combination of OpenSBI's fw_dynamic.bin,
> +u-boot-nodtb.bin and the device tree blob.
> +
> +Format the SD card (make sure the disk has GPT, otherwise use gdisk to switch)
> +
> +.. code-block:: bash
> +
> +       sudo sgdisk --clear \
> +         --set-alignment=2 \
> +         --new=1:4096:8191 --change-name=1:spl --typecode=1:2E54B353-1271-4842-806F-E436D6AF6985\
> +         --new=2:8192:16383 --change-name=2:uboot --typecode=2:BC13C2FF-59E6-4262-A352-B275FD6F7172  \
> +         --new=3:16384:1654784 --change-name=3:system --typecode=3:EBD0A0A2-B9E5-4433-87C0-68B6B72699C7 \
> +         /dev/sdb
> +
> +Copy U-Boot to the SD card
> +
> +.. code-block:: bash
> +
> +       sudo dd if=u-boot-spl.bin.normal.out of=/dev/sdb1
> +       sudo dd if=u-boot.itb of=/dev/sdb2
> +
> +       sudo mount /dev/sdb3 /mnt/
> +       sudo cp u-boot-spl.bin.normal.out /mnt/
> +       sudo cp u-boot.itb /mnt/
> +       sudo cp Image.gz /mnt/
> +       sudo cp initramfs.cpio.gz /mnt/
> +       sudo cp jh7110-starfive-visionfive-2.dtb /mnt/
> +       sudo umount /mnt
> +
> +Booting
> +~~~~~~~
> +
> +Once you plugin the sdcard and power up, you should see the U-Boot prompt.
> --
> 2.44.0

Would like to see something more Star64-specific since all of the
above is explained in the visionfive2 board docs already. How is the
Star64 different from VisionFive2?

What does the silkscreen say about network port labels? Which node in
'net list' corresponds to each labelled network port?

Can eMMC socket and SD Card be used at the same time? In what order
are they enumerated (SD Card is 0? or 1?)

Does USB work from U-Boot? Mention that unlike visionfive2 there is no
VL805 USB controller.

Are network ports reliable, if no then which port is more reliable at
this time or are both equal?

Early Star64 units shipped with uninitialized EEPROM contents and
these boards will not apply the fdt fixes correctly.  How to fix this
from U-Boot? i.e.

mac initialize  # Use defaults for VisionFive2
mac vendor "PINE64"
mac product_id "STAR64V1-2310-D008E000-01234567"  # 8GB Model, replace
01234567 with random number
mac product_id "STAR64V1-2310-D004E000-01234567   # 4GB Model, replace
01234567 with random number
mac pcb_revision c1  # Star64 V1.1
mac bom_revision "A"
mac mac0_address "6c:cf:39:aa:bb:cc"  # replace aa bb cc with random hex digits
mac mac1_address "6c:cf:39:aa:bb:cc"  # replace aa bb cc with random hex digits
mac write_eeprom

Is EEPROM Write Protect enable high (prevent write) normally?

How to visually identify the board revisions? Are there differences
that affect boot operation?

Do we know what board revisions correspond to with EEPROM data content
or is this not trustworthy?

For someone reading the documentation and not familiar with the board
it will be worth mentioning there is a physical PCIe slot.

-E