[PATCH v4 5/8] doc: add DeepComputing FML13V01 documentation

[Heinrich Schuchardt]

On 25.04.25 09:38, Maud Spierings wrote:
> On 4/24/25 13:26, E Shattow wrote:
>> Overall I think this patch is acceptable as-is and I'll be willing to
>> make a later series with my suggestions; it's documentation so it is
>> never really completed, I think, and I spend an hour or two editing then
>> decide that what I want to do is its own other series. None of the what
>> I'd like to suggest here should delay a PR for this series.
>>
>> On 4/24/25 05:13, Heinrich Schuchardt wrote:
>>> Describe building U-Boot for the board and booting.
>>>
>>> Carve out common information for JH7110 boards into an include.
>>>
>>> Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt at canonical.com>
>>> ---
> 
> [...]
> 
>>> +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
>>> +======= ========================
>>> +
>>> +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 UART
>>> +-----------------
>>> +
>>> +The boot ROM supports the X-modem protocol to upload
>>> +spl/u-boot-spl.bin.normal.out. U-Boot SPL support loading the FIT image
>>> +u-boot.itb via the Y-modem protocol.
>>> +
>>> +Due to restrictions of the boot ROM not all X-modem implementations are
>>> +compatible. The package tio (https://github.com/tio/tio) has been 
>>> found to be
>>> +usable.
>>
>> JH7110 Boot User Guide says "Since document release 1.2, boot from SD
>> Card or eMMC is no longer recommended. But to maintain the code
>> structure, the following SD/eMMC boot address allocations are modified
>> as "reserved". Be aware of this change when designing your device based
>> on JH7110." [1]
>>
>> 1:https://doc-en.rvspace.org/VisionFive2/Developer_Guide/ 
>> JH7110_Boot_UG.pdf
>>
>> So this is important we preserve documentation how SD-card and eMMC Boot
>> source modes can be prepared that are since dropped from official
>> documentation. Yet on my patch for bootph-pre-ram device-tree hints to
>> LKML there is Hal (StarFive) and some other people that want this
>> functionality of SD-card and eMMC boot to remain working in U-Boot even
>> though it's recommended against and dropped from official StarFive
>> documentation.
> 
> Can confirm that I would like this functionality to stay, as I've used 
> it a couple of times already on the fml13v01 board specifically to test 
> firmware before flashing it to spi flash.

The functionality is in the Boot ROM. So unless somebody changes the 
lithography mask it won't change.

> 
> I believe it is actually the default boot mode selected by deepcomputing 
> on new boards, but don't quote me on that.

The fml13v01 comes without installed eMMC. My board came with U-Boot on 
SPI flash.

> 
> I have only confirmed the sd card to work though, since my eMMC is my 
> main drive and is already full of efi/bootfs/rootfs.
> 
> I should try that uart booting at some point, I already use tio. Would 
> love to see a more detailed how to on it. I guess set to uart, then 
> ctrl+t x and then just send the spl, then ctrl+t x to send the FIT?

Ctrl+t x to send u-boot-spl.bin.normal.out.
Ctrl+t y to send u-boot.itb. We use Y-Modem at that stage.

https://docs.u-boot.org/en/v2025.01/board/starfive/milk-v_mars_cm.html
had this well described.

We can add in more detail again after this series.

Best regards

Heinrich

> 
> Kind regards,
> Maud
> 
>> I don't know, which is it? This appears to be an academic exercise to
>> make those deprecated boot modes working. It certainly belongs in
>> jh7110_common.rst as something interesting the hardware may be capable
>> of, but not as the recommended standard operating procedure.
>>
>> @ Hal can you describe what the JH7110 boot code is doing for SD-card
>> and eMMC Boot modes? What magic numbers and logic is this process? If
>> you want these boot modes to be functional then please help with the
>> documentation here that is now deleted from StarFive officially.
>>
>> With that,
>>
>> Reviewed-by: E Shattow <e at freeshell.de>