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.gitcd opensbimake 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_defconfigmake 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/sdb1sudo dd if=u-boot.itb of=/dev/sdb2sudo 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 valuesmac vendor PINE64mac pcb_revision c1mac bom_revision A## Device-specific values# Year 2023 week 10 production date, 8GB DRAM, optional eMMC, serial cdef01mac product_id STAR64V1-2310-D008E000-00cdef01# Last three bytes mac0: 0x7558 + serial number 0xcdef01mac mac0_address 6c:cf:39:ce:64:59# Last three bytes mac1: 0x7559 + serial number 0xcdef01mac 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-00cdef01env set ethaddr 6c:cf:39:ce:64:59env set eth1addr 6c:cf:39:ce:64:5aenv savereset-- 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