On 11/6/25 09:33, Hal Feng wrote:
On 27.10.25 03:53, Heinrich Schuchardt wrote:
Am 26. Oktober 2025 20:07:28 MEZ schrieb E Shattow <[email protected]>:
Hi Heinrich, thanks for the review.
On 10/26/25 02:56, Heinrich Schuchardt wrote:
On 10/24/25 09:33, E Shattow wrote:
Updates to the JH7110 common descripton:
- add detailed overview of JH-7110 SoC and boot process
- drop descriptions of deprecated StarFive loader modes
- refresh build directions grouped with SPL debug advice
- reduce usage instructions into common methods shared by supported
boards
Redundant/deprecated sections of each board doc are dropped
accordingly:
- deepcomputing fml13v01
- milk-v mars
- pine64 star64 (also add inclusion of JH7110 common description)
- visionfive2
Signed-off-by: E Shattow <[email protected]>
---
Preface to reviewers: SD Card / eMMC modes are officially deprecated
in the published StarFive JH-7110 Technical Reference Manual. The
request for supporting documentation was not answered in the
upstream review
The boot ROM was not changed. Ubuntu preinstalled images boot fine
with U-Boot on SD-card. Booting from eMMC works fine too with a bit
of patching of the first partition.
It is unfortunate that StarFive is not inclined to document how
booting from eMMC or SD-card works but this does not mean that it is
irrelevant to U-Boot users and developers.
Please, keep the existing information.
There is opportunity to do the work ourselves if we choose to[1] do or
otherwise I'm not convinced this information can stay. I will expand on
this, below.
process and accordingly was rejected from the upstream process. This
does not function anymore in U-Boot SPL to be loaded by BootROM with
the
[RGPIO1:RGPIO0]=1 and [RGPIO1:RGPIO0]=2 configurations. Use of SD
Card / eMMC within U-Boot Main is not affected and functions
normally. Aside, the effort is begun to reverse-engineer the BootROM
and gain an understanding about what we would be supporting; for
example the specific circumstance of the XMODEM too-man-NAK bug in
StarFive loader code, or introducing a patch upstream to accommodate
users that continue using deprecated modes.
Meanwhile the documentation needs to be updated to reflect what is
true and verifiable now.
The support enabled in starfive_visionfive2_defconfig for many
methods of data transfer is well-documented elsewhere and does not
vary enough to be repeated in the JH-7110 common description or that
of the supported board documents. This will be deserving of a brief
mention in a future update so that users may easily ref link to the
enabled methods in sections where they are documented. It is not
clear if this will belong in the common description or per-board so
it is omitted here.
There's some plainly wrong information remaining for the supported
boards also deserving of correction in a future update.
-E
---
doc/board/starfive/deepcomputing_fml13v01.rst | 32 -
doc/board/starfive/jh7110_common.rst | 597
+++++++++++++++---
doc/board/starfive/milk-v_mars.rst | 73 ---
doc/board/starfive/pine64_star64.rst | 77 +--
doc/board/starfive/visionfive2.rst | 449 -------------
5 files changed, 511 insertions(+), 717 deletions(-)
diff --git a/doc/board/starfive/deepcomputing_fml13v01.rst b/doc/
board/starfive/deepcomputing_fml13v01.rst
index 5d9612483b4..9777f4c6303 100644
--- a/doc/board/starfive/deepcomputing_fml13v01.rst
+++ b/doc/board/starfive/deepcomputing_fml13v01.rst
@@ -9,38 +9,6 @@ The DeepComputing Framework motherboard
(FLM13V01)
can be combined with a
U-Boot for the board uses the same binaries as the VisionFive 2 board.
Currently only serial console output is supported by mainline U-Boot.
-Building
---------
-
-Setup the cross compilation environment variable:
...snip...
+Zero Stage BootLoader
+^^^^^^^^^^^^^^^^^^^^^
+
+JH-7110 ZSBL is typically StarFive loader code in BootROM selected
+by
RGPIO2
+pull-down.
+
+====== ====== ======================================
+RGPIO1 RGPIO0 StarFive loader function @ 0x2A00_0000 ====== ======
+======================================
+0 0 1-bit QSPI Flash offset 0x0
+0 1 SDIO3.0 *(deprecated)*
+1 0 eMMC5.0 *(deprecated)*
I think we should replace "deprecated" by "not recommended by StarFive".
The deprecated loader functions are not reliable and new designs
substitute transistor logic that omits these modes. I did consider some
alternative word choices and "deprecated" gets the point across
quickly.>
+1 1 UART Serial XMODEM loader ====== ======
+======================================
+
+StarFive loader code is assumed to copy content to SRAM @
+0x0800_0000
and test
+for StarFive SPL header followed by a jump to SRAM.
"is assumed" means what here? Is it "We don't know?" or "It is the
BootROM's duty"? Please, provide an unambiguous description.
I agree, I don't like this word choice "is assumed", with the meaning
of "We don't know?"
Do you know what BootROM code does ? I think it looks like it does at
least what is described here, but there is some OTP and checksum action
that I don't understand myself.
What do you suggest to say here?
+
+First Stage BootLoader
+^^^^^^^^^^^^^^^^^^^^^^
+
...snip...
-
-Booting from SD-Card
---------------------
-
-The device boot ROM 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.
-
-Booting from eMMC
------------------
-
-The device boot ROM tries to load U-Boot SPL (u-boot-
spl.bin.normal.out) from
-sector 0 of the eMMC's main hardware partition. But this conflicts
with GPT -partitioning. Fortunately eMMC can alternatively load
U-Boot SPL from a backup -position.
-
-For U-Boot SPL (u-boot-spl.bin.normal.out) starting at sector 2048
(position
-0x100000) write the following bytes to the eMMC device after GPT
partitioning:
-
-======= ========================
-Address Bytes
-======= ========================
-0x0000 40 02 00 00 00 00 10 00
-0x0290 40 02 00 00 00 00 10 00
-======= ========================
Please, don't drop this information about booting from eMMC.
Best regards
Heinrich
If you have a code listing for BootROM instead which details these
address and byte references then I will be excited to learn more and
expand on our description with citations.
I do not, however, wish to continue with this booting from eMMC
information as it is. No matter how much time we both have sunk trying
to compare vendor BSP OS images, etc.:
- it is not a feature that is supported today in U-Boot SPL
- suggestion violates GUID Partition Table published standard
- what I do understand now about JH-7110 BootROM[1] is I have no
confidence in this information anymore about StarFive loader booting
U-Boot SPL from SD Card / eMMC
At our discretion we may contribute to this public document[1] and
there will be no hesitation from me to introduce - on the basis of
verifiable fact - upstream support and summary here for **what the
immutable StarFive loader in JH-7110 SoC is doing**. Going the other
way around looking at vendor BSP OS images is not acceptable to me
after having sunk multiple days into that effort and discussing with
you briefly in the past, there are too many unknowns and unexplained
errors and the result violates actually published standards.
1: https://codeberg.org/hrv/jhre
... snip
-E
Hello Hal and Minda,
Could you, please , chime in. As board maintainers and working for StarFive I
would like to hear your view.
Actually I was not clear about this problem before and it took me some days to
investigate.
Now Iet me explain why we did not recommend booting from SD card and eMMC.
The SD card boot mode is supported but the mmc driver of BootROM is not
compatible
with a few SD cards. If you can't boot from a SD card, you can change another
card for a try.
The eMMC boot mode loads SPL from sector 0, while the SD card boot mode loads
GPT
header from sector 1 and then finds the partition whose GUID is
2E54B353-1271-4842-806F-E436D6AF6985 to load SPL. So if we try to use GPT
partition in
eMMC, it will fail to boot and report CRC (stored at 0x290) failure. The
workaround is using
the backup load address. After the CRC failure happens, it will try to load the
SPL from the
backup address (stored at 0x4~0x7). That is why we write 0x00100000 to 0x4~0x7.
But this
workaround is not a standard process and may destroy the partition information
stored in
sector 0.
I suggest to keep the description of SD card / eMMC boot mode because the SD
card boot
mode actually works for most types of SD cards and the workaround eMMC boot
mode may
be useful to some developers.
Best regards,
Hal
How the CRC32 is calculated can be seen in tools/sfspl.c.
/**
* struct spl_hdr - header for SPL on JH7110
*
* All fields are low-endian.
*/
struct spl_hdr {
/** @offset: offset to SPL header (0x240) */
unsigned int offset;
/** @bkp_offs: address of backup SPL, defaults to
DEFAULT_BACKUP */
unsigned int bkp_offs;
/** @zero1: set to zero */
unsigned int zero1[159];
/** @version: header version, defaults to DEFAULT_VERSION */
unsigned int version;
/** @file_size: file size */
unsigned int file_size;
/** @hdr_size: size of the file header (0x400) */
unsigned int hdr_size;
/** @crc32: CRC32 */
unsigned int crc32;
/** @zero2: set to zero */
unsigned int zero2[91];
};
crc_check = crc32(0, &buf[hdr_size], file_size);
To not depend on any chance probably we should set filesize to 0 in
sector 0.
Best regards
Heinrich
