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

Thu Nov 6 14:49:41 CET 2025

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 <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

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