[v3,4/4] doc: spacemit: k3: Add Pico-ITX board

Add documentation for how to test the mainline U-Boot on SpacemiT
K3 Pico-ITX board, currently it still rely on using vendor FSBL.bin
file to initialize DDR and boot U-Boot proper, and the opensbi
firmware is built from an on-going mainline branch.

Signed-off-by: Yixun Lan <dlan@kernel.org>
---
 doc/board/spacemit/index.rst             |   1 +
 doc/board/spacemit/spacemit-pico-itx.rst | 204 +++++++++++++++++++++++++++++++
 2 files changed, 205 insertions(+)

Hi Yixun,

On 10/2/26 17:34, Yixun Lan wrote:
> Add documentation for how to test the mainline U-Boot on SpacemiT
> K3 Pico-ITX board, currently it still rely on using vendor FSBL.bin
> file to initialize DDR and boot U-Boot proper, and the opensbi
> firmware is built from an on-going mainline branch.
> 
> Signed-off-by: Yixun Lan <dlan@kernel.org>
> ---
>  doc/board/spacemit/index.rst             |   1 +
>  doc/board/spacemit/spacemit-pico-itx.rst | 204 +++++++++++++++++++++++++++++++
>  2 files changed, 205 insertions(+)
> 
> diff --git a/doc/board/spacemit/index.rst b/doc/board/spacemit/index.rst
> index 71854e5735b..51918f0acc7 100644
> --- a/doc/board/spacemit/index.rst
> +++ b/doc/board/spacemit/index.rst
> @@ -8,4 +8,5 @@ SpacemiT
>     bananapi-f3
>     k1-mmc
>     k1-spl
> +   spacemit-pico-itx
>  
> diff --git a/doc/board/spacemit/spacemit-pico-itx.rst b/doc/board/spacemit/spacemit-pico-itx.rst
> new file mode 100644
> index 00000000000..dd29e3c31c8
> --- /dev/null
> +++ b/doc/board/spacemit/spacemit-pico-itx.rst
> @@ -0,0 +1,204 @@
> +.. SPDX-License-Identifier: GPL-2.0-or-later
> +
> +SpacemiT K3 Pico-ITX
> +====================
> +
> +Building
> +~~~~~~~~
> +1. Install the SpacemiT riscv cross compile toolchain_, or skip it if riscv toolchain is installed.
> +
> +.. _toolchain: https://archive.spacemit.com/toolchain/
> +

Avoid the advertisement for any unnecessary vendor-specific information.

The packaged toolchain from any generic Linux distro is fine enough to
build with as "1. Add a RISC-V toolchain to your PATH." and no other
explanation is required.

I have tested with Debian forky/testing for example, it is fine. Code
size differences between output of GCC major versions may be detailed in
a future update if it becomes important.

> +2. Setup cross compilation environment variable:
> +
> +.. code-block:: console
> +
> +   export CROSS_COMPILE=<riscv64 toolchain prefix, e.g /opt/spacemit/bin/riscv64-unknown-linux-gnu->
> +

Likewise, it is enough to have "2. Set a cross-compilation environment
variable if needed: export CROSS_COMPILE=<riscv64 toolchain prefix>"

There is much documentation about compiling U-Boot at
doc/build/index.rst and so do not name a specific vendor toolchain path
name here.

> +3. Before building U-Boot, OpenSBI should be built first. OpenSBI can be
> +built for SpacemiT K1 SoC as below:

built for SpacemiT K3 SoC ?

However it is clearer to re-phrase that as a statement of requirements.
"3. U-Boot for SpacemiT K3 SoC requires OpenSBI in-development generic
platform object fw_dynamic.bin to be included in the Flattened Image
Tree blob. OpenSBI may be first built as below: ..."

Please if it will help you then do copy any build examples adapted from
my own writing in doc/board/starfive/jh7110_common.rst which contains a
small error in build command details corrected at
https://lore.kernel.org/u-boot/20260924063843.8934-1-e@freeshell.de/

Additional phrasing may be as "Review the OpenSBI developer mailing list
archives for patches to apply in support of SpacemiT K3 Pico-ITX". Let
this be generic enough that we are not dead-linking to something 10
years later when a user is viewing this old document from the future.

> +
> +.. code-block:: console
> +
> +   git clone https://github.com/spacemit-com/opensbi-upstream opensbi
> +   cd opensbi
> +   make PLATFORM=generic

Please refer to upstream directly. I appreciate to make it convenient
with patches curated on a fork repository but this is not durable for
documentation purpose, is this going to exist in 2 years? 10 years? 20
years?. Mailing list archives are durable and if we depend on OpenSBI
then I expect at least upstream OpenSBI git repository to be durable, too.

> +
> +4. Then build U-Boot as following:
> +
> +.. code-block:: console
> +
> +   cd <U-Boot-dir>
> +   make spacemit_k3_defconfig
> +   make OPENSBI=<OpenSBI-dir>/build/platform/generic/firmware/fw_dynamic.bin
> +
> +This will generate u-boot.itb
> +
> +Testing
> +~~~~~~~
> +Currently, in this stage, the U-Boot SPL isn't ready, and has no ddr initialization code

Instead, as "Currently there is no U-Boot SPL build target. It is
required to use 'FSBL.bin' vendor board support package SPL for DDR
initialization and testing u-boot.itb"

May SPI NOR be erased empty? what exactly must be present in SPI NOR for
successful testing?

> +Thus please test with fasboot command via USB download.

fastboot

> +
> +First, retrieve Bianbu Linux image from archive_ and extract the FSBL.bin firmware.

We should build any out-of-tree dependencies (FSBL.bin) from from source
if it is possible. This is a cheap operation to 'git remote add -f
spacemit-com https://...spacemit-com/uboot-2022.10' on an existing
u-boot git repo.

Assume SPI NOR content is erased. Is there something vendor-specific you
need that is not available by compiling spacemit-com k3-br-v1.0.y branch?

> +
> +Second, hold the FEL button of Pico-ITX board, then press reset button and release it .
> +The board will enter into firmware download mode.
> +
> +.. code-block:: none
> +
> +   sys: 0x10001200
> +   bm:2
> +   usb_init : enter 3296,3072
> +   usb_core_init : enter
> +   DWC3_GRXTHRCFG:0x4400000
> +   ROM: usb download handler
> +    rst
> +   done H
> +   setup= 0x1000680 0x400000,
> +    rst
> +   done H
> +   setup= 0x290500 0x0,
> +   setup= 0x1000680 0x120000,
> +   setup= 0x2000680 0x90000,
> +   setup= 0x2000680 0x200000,
> +   setup= 0x3000680 0xff0000,
> +   setup= 0x3020680 0xff0409,
> +   setup= 0x3010680 0xff0409,
> +   setup= 0x10900 0x0,
> +   usb_rx_bytes : start len[4096]
> +   setup= 0x3020680 0xff0409,
> +   setup= 0x3040680 0xff0409,
> +
> +Run following command to test:
> +
> +.. code-block:: console
> +
> +   fastboot stage FSBL.bin
> +   fastboot continue
> +   sleep 10
> +   fastboot stage u-boot.itb
> +   fastboot continue
> +
> +.. _archive: https://archive.spacemit.com/image/k3/version/bianbu/v4.0.7/
> +.. _uboot: https://bianbu-linux.spacemit.com/en/device/boot#21-firmware-layout
> +
> +Booting
> +~~~~~~~
> +Sample boot log
> +~~~~~~~~~~~~~~~
> +.. code-block:: none
> +
> +   sys: 0x10001200
> +   bm:2
> +   usb_init : enter 3296,3072
> +   usb_core_init : enter
> +   DWC3_GRXTHRCFG:0x4400000
> +   ROM: usb download handler
> +    rst
> +   done H
> +   setup= 0x1000680 0x400000,
> +    rst
> +   done H
> +   setup= 0x2f0500 0x0,
> +   setup= 0x1000680 0x120000,
> +   setup= 0x2000680 0x90000,
> +   setup= 0x2000680 0x200000,
> +   setup= 0x3000680 0xff0000,
> +   setup= 0x3020680 0xff0409,
> +   setup= 0x3010680 0xff0409,
> +   setup= 0x10900 0x0,
> +   usb_rx_bytes : start len[4096]
> +   setup= 0x3020680 0xff0409,
> +   setup= 0x3040680 0xff0409,
> +   fastboot_handle_command: max-download-size
> +   usb_tx_bytes : start len[14]
> +   usb_rx_bytes : start len[4096]
> +   fastboot_handle_command: 00072b20
> +   Starting download of 469792 bytes
> +   usb_tx_bytes : start len[12]
> +   usb_rx_bytes : start len[469792]
> +   usb_tx_bytes : start len[4]
> +   usb_rx_bytes : start len[4096]
> +   fastboot_handle_command: continue
> +   usb_tx_bytes : start len[4]
> +   j...
> +
> +   U-Boot SPL 2022.10 (Sep 07 2026 - 11:31:13 +0000)
> +   LPDDR5 total size: 16 GB, data rate: 6400 MT/s
> +   DDR training consume 5625ms
> +   ..
> +   OpenSBI v1.9-72-g13a401f8
> +      ____                    _____ ____ _____
> +     / __ \                  / ____|  _ \_   _|
> +    | |  | |_ __   ___ _ __ | (___ | |_) || |
> +    | |  | | '_ \ / _ \ '_ \ \___ \|  _ < | |
> +    | |__| | |_) |  __/ | | |____) | |_) || |_
> +     \____/| .__/ \___|_| |_|_____/|____/_____|
> +           | |
> +           |_|
> +
> +   Platform Name               : SpacemiT K3 Pico-ITX
> +   Platform Features           : medeleg
> +   Platform HART Count         : 8
> +   Platform HART Protection    : pmp
> +   Platform IPI Device         : aclint-mswi
> +   Platform Timer Device       : aclint-mtimer @ 24000000Hz
> +   Platform Console Device     : uart8250
> +   Platform HSM Device         : spacemit-k3-hsm
> +   Platform PMU Device         : ---
> +   Platform Reboot Device      : spacemit-p1-reset
> +   Platform Shutdown Device    : spacemit-p1-reset
> +   Platform Suspend Device     : ---
> +   Platform CPPC Device        : ---
> +   Firmware Base               : 0x100000000
> +   Firmware Size               : 416 KB
> +   Firmware RW Offset          : 0x40000
> +   Firmware RW Size            : 160 KB
> +   Firmware Heap Offset        : 0x57000
> +   Firmware Heap Size          : 68 KB (total), 1 KB (reserved), 14 KB (used), 52 KB (free)
> +   Firmware Scratch Size       : 4096 B (total), 1472 B (used), 2624 B (free)
> +   Runtime SBI Version         : 3.0
> +   Standard SBI Extensions     : time,rfnc,ipi,base,hsm,srst,pmu,dbcn,fwft,legacy,dbtr,sse
> +   Experimental SBI Extensions : none
> +
> +   Domain0 Name                : root
> +   Domain0 Init Order          : 0xffffffff
> +   Domain0 Boot HART           : 0
> +   Domain0 HARTs               : 0x0*,0x1*,0x2*,0x3*,0x4*,0x5*,0x6*,0x7*
> +   Domain0 Region00            : 0x0000000100000000-0x000000010003ffff M: (F,R,X) S/U: ()
> +   Domain0 Region01            : 0x0000000100040000-0x000000010007ffff M: (F,R,W) S/U: ()
> +   Domain0 Region02            : 0x00000000d4017000-0x00000000d4017fff M: (I,R,W) S/U: (R,W)
> +   Domain0 Region03            : 0x00000000e081c000-0x00000000e081ffff M: (I,R,W) S/U: ()
> +   Domain0 Region04            : 0x0000000000000000-0xffffffffffffffff M: () S/U: (R,W,X)
> +   Domain0 Next Address        : 0x0000000102000000
> +   Domain0 Next Arg1           : 0x0000000102091398
> +   Domain0 Next Mode           : S-mode
> +   Domain0 SysReset            : yes
> +   Domain0 SysSuspend          : yes
> +
> +   Boot HART ID                : 0
> +   Boot HART Domain            : root
> +   Boot HART Priv Version      : v1.12
> +   Boot HART Base ISA          : rv64imafdcbvhx
> +   Boot HART ISA Extensions    : smaia,smstateen,sscofpmf,sstc,zicntr,zihpm,smcntrpmf,zicboz,zicbom,svpbmt,sdtrig,svade,ssstateen,v,f,d
> +   Boot HART PMP Count         : 16
> +   Boot HART PMP Granularity   : 12 bits
> +   Boot HART PMP Address Bits  : 38
> +   Boot HART MHPM Info         : 16 (0x0007fff8)
> +   Boot HART Debug Triggers    : 4 triggers
> +   Boot HART MIDELEG           : 0x0000000000003666
> +   Boot HART MEDELEG           : 0x0000000000f0b509
> +
> +   <debug_uart>
> +
> +
> +   U-Boot 2026.10-rc4-00501-g9fba7b59df42 (Sep 22 2026 - 13:08:33 +0000)
> +
> +   DRAM:  16 GiB
> +   Core:  433 devices, 15 uclasses, devicetree: separate
> +   Loading Environment from nowhere...Loading Environment from nowhere... OK
> +   In:    serial@d4017000
> +   Out:   serial@d4017000
> +   Err:   serial@d4017000
> +   Net:   No ethernet found.
> +   =>
> 

Thanks for your work on this,

-E

Hi E Shattow, 

On 05:43 Sat 03 Oct     , E Shattow wrote:
> Hi Yixun,
> 
> On 10/2/26 17:34, Yixun Lan wrote:
> > Add documentation for how to test the mainline U-Boot on SpacemiT
> > K3 Pico-ITX board, currently it still rely on using vendor FSBL.bin
> > file to initialize DDR and boot U-Boot proper, and the opensbi
> > firmware is built from an on-going mainline branch.
> > 
> > Signed-off-by: Yixun Lan <dlan@kernel.org>
> > ---
> >  doc/board/spacemit/index.rst             |   1 +
> >  doc/board/spacemit/spacemit-pico-itx.rst | 204 +++++++++++++++++++++++++++++++
> >  2 files changed, 205 insertions(+)
> > 
> > diff --git a/doc/board/spacemit/index.rst b/doc/board/spacemit/index.rst
> > index 71854e5735b..51918f0acc7 100644
> > --- a/doc/board/spacemit/index.rst
> > +++ b/doc/board/spacemit/index.rst
> > @@ -8,4 +8,5 @@ SpacemiT
> >     bananapi-f3
> >     k1-mmc
> >     k1-spl
> > +   spacemit-pico-itx
> >  
> > diff --git a/doc/board/spacemit/spacemit-pico-itx.rst b/doc/board/spacemit/spacemit-pico-itx.rst
> > new file mode 100644
> > index 00000000000..dd29e3c31c8
> > --- /dev/null
> > +++ b/doc/board/spacemit/spacemit-pico-itx.rst
> > @@ -0,0 +1,204 @@
> > +.. SPDX-License-Identifier: GPL-2.0-or-later
> > +
> > +SpacemiT K3 Pico-ITX
> > +====================
> > +
> > +Building
> > +~~~~~~~~
> > +1. Install the SpacemiT riscv cross compile toolchain_, or skip it if riscv toolchain is installed.
> > +
> > +.. _toolchain: https://archive.spacemit.com/toolchain/
> > +
> 
> Avoid the advertisement for any unnecessary vendor-specific information.
> 
Ok
> The packaged toolchain from any generic Linux distro is fine enough to
> build with as "1. Add a RISC-V toolchain to your PATH." and no other
> explanation is required.
> 
> I have tested with Debian forky/testing for example, it is fine. Code
> size differences between output of GCC major versions may be detailed in
> a future update if it becomes important.
> 
Ok, I generally agree, any riscv toolchain should works fine here,
no specific requirement, this is just a copy-and-poaste from K1 doc,
and should consider as one of many ways to setup compiling toolchain

> > +2. Setup cross compilation environment variable:
> > +
> > +.. code-block:: console
> > +
> > +   export CROSS_COMPILE=<riscv64 toolchain prefix, e.g /opt/spacemit/bin/riscv64-unknown-linux-gnu->
> > +
> 
> Likewise, it is enough to have "2. Set a cross-compilation environment
> variable if needed: export CROSS_COMPILE=<riscv64 toolchain prefix>"
> 
> There is much documentation about compiling U-Boot at
> doc/build/index.rst and so do not name a specific vendor toolchain path
> name here.
> 
Ok
> > +3. Before building U-Boot, OpenSBI should be built first. OpenSBI can be
> > +built for SpacemiT K1 SoC as below:
> 
> built for SpacemiT K3 SoC ?
> 
> However it is clearer to re-phrase that as a statement of requirements.
> "3. U-Boot for SpacemiT K3 SoC requires OpenSBI in-development generic
> platform object fw_dynamic.bin to be included in the Flattened Image
> Tree blob. OpenSBI may be first built as below: ..."
> 
> Please if it will help you then do copy any build examples adapted from
> my own writing in doc/board/starfive/jh7110_common.rst which contains a
> small error in build command details corrected at
> https://lore.kernel.org/u-boot/20260924063843.8934-1-e@freeshell.de/
> 
I will try to do some ajdustment to make it more generic..

> Additional phrasing may be as "Review the OpenSBI developer mailing list
> archives for patches to apply in support of SpacemiT K3 Pico-ITX". Let
> this be generic enough that we are not dead-linking to something 10
> years later when a user is viewing this old document from the future.
> 
But, well, either way isn't perfect, I didn't expect this is an unchanged
doc which will last 10years long, instead it should be kept improved.

> > +
> > +.. code-block:: console
> > +
> > +   git clone https://github.com/spacemit-com/opensbi-upstream opensbi
> > +   cd opensbi
> > +   make PLATFORM=generic
> 
> Please refer to upstream directly. I appreciate to make it convenient
> with patches curated on a fork repository but this is not durable for
> documentation purpose, is this going to exist in 2 years? 10 years? 20
Shouldn't be problem for 2years, while not sure for more than 10years,
but I don't think this is really a problem, see below

> years?. Mailing list archives are durable and if we depend on OpenSBI
> then I expect at least upstream OpenSBI git repository to be durable, too.
> 
I'd hope patches for opensbi will be finally accepted into mainline, then
update the doc here accordingly, providing a fork repo is just a conveniet
way for people to download, I could adjust to use mainline opensbi repo +
applying extra patches, but to be honest, I don't see that's much
different.. so, I'd rather not change it now, or let's say, do update the
doc when above fork repo is really broken/or opensbi patches accepted.

> > +
> > +4. Then build U-Boot as following:
> > +
> > +.. code-block:: console
> > +
> > +   cd <U-Boot-dir>
> > +   make spacemit_k3_defconfig
> > +   make OPENSBI=<OpenSBI-dir>/build/platform/generic/firmware/fw_dynamic.bin
> > +
> > +This will generate u-boot.itb
> > +
> > +Testing
> > +~~~~~~~
> > +Currently, in this stage, the U-Boot SPL isn't ready, and has no ddr initialization code
> 
> Instead, as "Currently there is no U-Boot SPL build target. It is
> required to use 'FSBL.bin' vendor board support package SPL for DDR
> initialization and testing u-boot.itb"
> 
Ok

> May SPI NOR be erased empty? what exactly must be present in SPI NOR for
> successful testing?
> 
Doesn't matter if there is fw present in SPI NOR, for my testing, my
board do has SPI nor firmware exist

> > +Thus please test with fasboot command via USB download.
> 
> fastboot
> 
thanks

> > +
> > +First, retrieve Bianbu Linux image from archive_ and extract the FSBL.bin firmware.
> 
> We should build any out-of-tree dependencies (FSBL.bin) from from source
> if it is possible. This is a cheap operation to 'git remote add -f
> spacemit-com https://...spacemit-com/uboot-2022.10' on an existing
> u-boot git repo.
> 
> Assume SPI NOR content is erased. Is there something vendor-specific you
> need that is not available by compiling spacemit-com k3-br-v1.0.y branch?
> 
I don't want to put too much effort to document about building vendor-specific
firmware.. currently, providing one way to test is enough, since there is a
work-on-porgress project, and we target having a mainline SPL support in
tree finally