K3 Pico ITX

Factory pre-installed BSP

K3 Pico ITX factory pre-installed vendor BSP U-Boot is by default configured bootdelay=0 and to read env_k3.txt on the onboard user flash storage boot partition scsi 0:2

Access vendor BSP U-Boot commandline

Use any of the following methods to access the vendor BSP U-Boot commandline

Power-on board and hold (s) key approximately 10 seconds to interrupt Autoboot with serial terminal session or attached USB keyboard
Boot the pre-installed vendor BSP Linux OS and indirectly override bootdelay=0
```
   1  echo "bootdelay=-1" | sudo tee -a /boot/env_k3.txt
```
Boot the pre-installed vendor BSP Linux OS and directly edit bootdelay=0
```
   1  sudo apt-install u-boot-tools
   2  echo "/dev/mtd3 0x0 0x4000" | tee $HOME/fw_env.config
   3  echo "bootdelay=-1" | sudo fw_setenv -c fw_env.config -s -
```

EFI crash bug

A known bug in vendor U-Boot misses calling miiphy_init() before MDIO access in EFI code path, resulting in a crash.

   1 => efidebug devices
   2     Unhandled exception: Load access fault
   3     EPC: 00000003fdf544a0 RA: 00000003fdecd7a8 TVAL: debe2ea238a2c520
   4     EPC: 00000001020b04a0 RA: 00000001020297a8 reloc adjusted
   5     Code: 94e3 fec7 8023 0007 8067 0000 0713 0005 (4683 0007)
   6     resetting ...
   7

The workaround is to run any U-Boot command that will call miiphy_init() e.g. ping 127.0.0.1 before EFI code path.

Install Debian

Linux Kernel 7.1 in Debian testing archives can boot an initramfs having an UART serial console, however a bug with ethernet networking initialization is triggered on debian-installer probe of network hardware. There is no storage functionality supported in this kernel for the SpacemiT K3 platform.

Linux Kernel 7.2 adds USB platform support which makes storage and networking possible.

Linux Kernel 7.3rc1 has several fixes queued which resolve the network driver initialization bugs.

A kernel package may be built and then initramfs for debian-installer modified to make it possible to install the resulting kernel package into the Debian installation target before first boot.

Prepare mainline Linux kernel and custom debian-installer netinst

Build the mainline Linux kernel:

   1 cat > /etc/apt/sources.list.d/debian-experimental.sources << EOF
   2 Types: deb deb-src
   3 URIs: http://deb.debian.org/debian
   4 Suites: experimental
   5 Components: main
   6 Signed-By: /usr/share/keyrings/debian-archive-keyring.gpg
   7 EOF
   8 
   9 dpkg --add-architecture riscv64
  10 apt update
  11 
  12 apt install -t experimental -y linux-config-7.2:riscv64
  13 
  14 apt install -y ca-certificates curl
  15 curl -LO https://git.kernel.org/torvalds/t/linux-7.3-rc1.tar.gz
  16 tar zxvf linux-7.3-rc1.tar.gz
  17 
  18 pushd linux-7.3-rc1
  19 apt install -y bison crossbuild-essential-riscv64 flex
  20 xzcat /usr/src/linux-config-7.2/config.riscv64_none_riscv64.xz > .config
  21 scripts/config --enable DEBUG_INFO_NONE --undefine CONFIG_DEBUG_INFO_DWARF_TOOLCHAIN_DEFAULT
  22 make ARCH=riscv CROSS_COMPILE=riscv64-linux-gnu- olddefconfig
  23 apt install -y bc debhelper kmod libdw-dev libssl-dev python3 rsync libssl-dev:riscv64
  24 make ARCH=riscv CROSS_COMPILE=riscv64-linux-gnu- KDEB_CHANGELOG_DIST=unreleased -j$(nproc) bindeb-pkg LOCALVERSION=-mainline
  25 popd

Customize debian-installer netinst:

   1 apt install -y cpio curl fakeroot
   2 curl -L https://deb.debian.org/debian/dists/trixie/main/installer-riscv64/current/images/netboot/netboot.tar.gz | tar xz ./debian-installer
   3 fakeroot  # enter fakeroot environment to preserve initrd permissions
   4 gzip -dc debian-installer/riscv64/initrd.gz | cpio -id --directory=initrd
   5 dpkg -x linux-image-*mainline*_riscv64.deb initrd/custom
   6 gzip -dc initrd/custom/boot/vmlinuz-* > debian-installer/riscv64/linux-custom
   7 mv initrd/lib/modules initrd/custom/
   8 mv initrd/custom/lib/modules initrd/lib/
   9 mv initrd/custom/usr/lib/* debian-installer/device-tree-custom
  10 find initrd -path initrd/custom -prune -o -printf '%P\0' | cpio -0oH newc --directory=initrd | gzip -c > debian-installer/riscv64/initrd-custom.gz
  11 exit  # leave fakeroot environment
  12

There should now be linux-image-*mainline*_riscv64.deb file in ./ directory, linux-custom and initrd-custom.gz files in ./debian-installer/riscv64/ directory, and spacemit/k3-pico-itx.dtb in ./debian-installer/device-tree-custom/ directory. Prepare a thumbdrive USB MSC device with a copy of the ./linux-image-*mainline*_riscv64.deb file and ./debian-installer directory to the root of any U-Boot compatible filesystem (recommended is FAT32 on the first partition usb 0:1).

Booting Linux mainline kernel and custom debian-installer netinst from USB MSC

Insert the USB MSC device containing the prepared Linux mainline linux-image-*mainline*_riscv64.deb file and customized ./debian-installer netinst directory.
Insert the USB MSC device target media for Debian 13 Trixie installation. Only USB MSC is viable as of late May 2026 until future when more of K3 platform is upstream. This may be the same media as the prepared custom debian-installer netinst files (above) to overwrite the device or install to a non-overlapping partition.
Power-on the K3 Pico-ITX board and with access to U-Boot command-line (see Access vendor BSP U-Boot commandline above):

   1 load usb 0:1 $fdt_addr_r /debian-installer/device-tree-custom/spacemit/k3-pico-itx.dtb
   2 load usb 0:1 $kernel_addr_r /debian-installer/riscv64/linux-custom
   3 load usb 0:1 $ramdisk_addr_r /debian-installer/riscv64/initrd-custom.gz
   4 env set bootargs 'initrd='$ramdisk_addr_r',0x'$filesize
   5 ping 127.0.0.1; bootefi $kernel_addr_r $fdt_addr_r
   6

Copy prepared files to debian-installer session

During the first step of installation, before answering any prompts:

Advance screen text window to the (n)ext screen window for access to a command line prompt

   1 (Control-a,n)

Example: Copy linux-image-*mainline*_riscv64.deb file from USB MSC

   1 mount -t vfat /dev/sda1 /mnt
   2 cp -a /mnt/linux-image-*mainline*_riscv64.deb /tmp
   3 umount /mnt

Return screen text window to the (p)revious screen window and continue with the installation

   1 (Control-a,p)

Common part

From then on are the familiar steps in sequence for a debian-installer workflow.

Installation notes:

The help text at set up users and passwords prompt may be obscured, it reads that if you want to enable sudo instead of a root password then enter twice a blank password when asked to configure a root password.
EFI System Partition must be sized large enough to contain two copies of Grub2 EFI + U-Boot EFI environment variable storage + all riscv64 devicetree blob files, of about 1MiB sum total. However, for wide compatibility the minimum recommended ESP sizing should be of length 260MiB (~272MB). As of Debian Trixie release the use of Grub2 EFI avoids the need of Linux kernel and initial ramdisk images stored on the ESP and so the ESP does not need to be sized any larger than the minimum.
Swap partition is recommended for NVMe storage and should be omitted on slower or wear-cycle sensitive media such as SD card.
When asked if you want to install for removable media a "No" answer installs Grub2 on EFI System Partition as EFI/debian/grubriscv64.efi while a default "Yes" answer will place an additional copy of the Grub2 bootloader as EFI/BOOT/BOOTRISCV64.EFI. Choose "Yes" so that U-Boot EFI will find the Grub2 bootloader automatically.

Install with prepared Linux mainline kernel

Installation of prepared Linux mainline kernel may be configured during the last step of Debian 13 Trixie debian-installer as follows. During the last step of installation, at the Finish the installation: Installation complete prompt: