[PATCH] doc: board: starfive: update jh7110 common description

Hal Feng hal.feng at starfivetech.com
Thu Nov 6 09:33:47 CET 2025 

> On 27.10.25 03:53, Heinrich Schuchardt wrote:
> Am 26. Oktober 2025 20:07:28 MEZ schrieb E Shattow <e at freeshell.de>:
> >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 <e at freeshell.de>
> >>> ---
> >>> 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

More information about the U-Boot mailing list