[2/2,v5] 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

Changes since v2

- Remove extra params to
- Clarification on boot section
- Add entry on MAC adresses and how to correct them

Changes	since v3

- Rebase against d678a59d2d

Changes since v4

- Rework and expand docs on boot selection switches and overriding
  MAC addresses
- Fix warnings and underline width
---
 doc/board/starfive/index.rst         |   1 +
 doc/board/starfive/pine64_star64.rst | 201 +++++++++++++++++++++++++++
 2 files changed, 202 insertions(+)
 create mode 100644 doc/board/starfive/pine64_star64.rst

On Wed, May 22, 2024 at 12:13 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
>
> Changes since v2
>
> - Remove extra params to
> - Clarification on boot section
> - Add entry on MAC adresses and how to correct them
>
> Changes since v3
>
> - Rebase against d678a59d2d
>
> Changes since v4
>
> - Rework and expand docs on boot selection switches and overriding
>   MAC addresses
> - Fix warnings and underline width
> ---
>  doc/board/starfive/index.rst         |   1 +
>  doc/board/starfive/pine64_star64.rst | 201 +++++++++++++++++++++++++++
>  2 files changed, 202 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 d369b986cc..72ab6ddfbf 100644
> --- a/doc/board/starfive/index.rst
> +++ b/doc/board/starfive/index.rst
> @@ -8,4 +8,5 @@ StarFive
>
>     milk-v_mars
>     milk-v_mars_cm
> +   pine64_star64
>     visionfive2
> diff --git a/doc/board/starfive/pine64_star64.rst b/doc/board/starfive/pine64_star64.rst
> new file mode 100644
> index 0000000000..52e9a90791
> --- /dev/null
> +++ b/doc/board/starfive/pine64_star64.rst
> @@ -0,0 +1,201 @@
> +.. 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
> +
> +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
> +
> +::
> +
> +    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.
> +
> +Boot source selection
> +~~~~~~~~~~~~~~~~~~~~~
> +
> +Boot mode is selected by an MSEL-DIP marked S1804 and GPIO_0 position adjacent
> +to the 40pin GPIO header. ON/ONKE and number markings of the MSEL-DIP are
> +misleading; Instead refer to the ``L`` (0) and ``H`` (1) silkscreen for
> +accurate selection.
> +
> ++ (QSPI) Flash: 00
> ++ SD: 01
> ++ EMMC: 10
> ++ UART: 11
> +
> +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.
> +
> +Serial Number and MAC address issues
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +U-Boot requires valid EEPROM data to determine which board-specific fix-up to
> +apply at runtime. This affects the size of memory initialized, network mac
> +address numbering, and tuning of the network PHYs.
> +
> +The Star64 does not currently ship with unique serial numbers per-device.
> +Devices follow a pattern where the last mac address bytes are a sum of 0x7558
> +and the serial number (lower port mac0), or a sum of 0x7559 and the serial
> +number (upper port mac1).
> +
> +As tested there are several 4gb model units where the serial number and network
> +mac addresses collide with other devices (serial
> +``STAR64V1-2310-D004E000-00000005``, MACs ``6c:cf:39:00:75:61``,
> +``6c:cf:39:00:75:62``)
> +
> +Some early Star64 boards shipped with an uninitialized EEPROM and no write
> +protect pull-up resistor in place. Later units of all 4gb and 8gb models
> +sharing the same serial number in EEPROM data will have this problem that the
> +network mac addresses are alike between different models and this may be
> +corrected by defeating the write protect resistor to write new values. As an
> +alternative to this, it may be worked around by overriding the mac addresses
> +via U-Boot environment variables.
> +
> +It is required for any unit having uninitialized EEPROM and recommended for
> +all later Star64 4gb model units (not properly serialized) to have decided on a
> +new 6-byte serial number. This serial number should be high enough to
> +avoid collision with other JH7110 boards and low enough not to overflow i.e.
> +between ``cafe00`` and ``f00d00``.
> +
> +Update EEPROM values
> +^^^^^^^^^^^^^^^^^^^^
> +
> +1. Prepare EEPROM data in memory
> +
> +::
> +
> +       ## When there is no error to load existing data:
> +       mac read_eeprom
> +
> +       ## When there is an error to load non-existing data:
> +       # "DRAM:  Not a StarFive EEPROM data format - magic error"
> +       mac initialize
> +
> +2. Set Star64 values
> +
> +::
> +
> +       ## Common values
> +       mac vendor PINE64
> +       mac pcb_revision c1
> +       mac bom_revision A
> +
> +       ## Device-specific values
> +       # Year 2023 week 10 production date, 8GB DRAM, optional eMMC, serial cdef01
> +       mac product_id STAR64V1-2310-D008E000-00cdef01
> +
> +       # Last three bytes mac0: 0x7558 + serial number 0xcdef01
> +       mac mac0_address 6c:cf:39:ce:64:59
> +
> +       # Last three bytes mac1: 0x7559 + serial number 0xcdef01
> +       mac mac1_address 6c:cf:39:ce:64:5a
> +
> +3. Defeat write-protect pull-up resistor (if installed) and write to EEPROM
> +
> +::
> +
> +       mac write_eeprom
> +
> +Set Variables in U-Boot
> +^^^^^^^^^^^^^^^^^^^^^^^
> +
> +.. note:: Changing just the serial number will not alter your MAC address
> +
> +The MAC addresses may be "set" as follows by writing as a custom config to SPI
> +(Change the last 3 bytes of MAC addreses as appropriate):
> +
> +::
> +
> +       env set serial# STAR64V1-2310-D008E000-00cdef01
> +       env set ethaddr 6c:cf:39:ce:64:59
> +       env set eth1addr 6c:cf:39:ce:64:5a
> +       env save
> +       reset
> --
> 2.44.0
>
>

I understand setting $serial# environment variable to be more
illustrative than prescriptive. I think this should be a comment to
guide the setting of ethaddr and eth1addr but not itself be set by the
user. With that:

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