Message ID | 6Yk7L2-xTxcUnQdR0tk_SVFsR-REvvBdSSzDPivTKNeM_3-wlFKeIQtDp1cJTjjOoO9P54bPe_q51mO1PvGF7e6Q-Tqo0k-F2QoLP6Tn8ss=@protonmail.com |
---|---|
State | Accepted |
Commit | a0dce092222b9a67f45b22e84a163ef638eb4ee0 |
Delegated to: | Andes |
Headers | show |
Series | [1/2,v5] board: starfive: support Pine64 Star64 board | expand |
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>
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
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