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

Sun Oct 26 20:07:28 CET 2025

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