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

Sun Oct 26 20:52:32 CET 2025

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.

Best regards

Heinrich