docs/system/riscv: add documentation for k230 machine
Signed-off-by: Chao Liu <chao.liu.zevorn@gmail.com> Acked-by: Alistair Francis <alistair.francis@wdc.com> Message-ID: <81d2e2fa42ecabf638f841321cf36cee8f10af01.1781246408.git.chao.liu@processmission.com> Signed-off-by: Alistair Francis <alistair.francis@wdc.com>
Chao Liu committed
Jun 12, 2026 at 15:04 UTC
b3fe55196f080e113129065dc19896e5cac8a3cc
3 files changed
+115
MAINTAINERS
+1
@@ -1790,6 +1790,7 @@ K230 Machines
1790
M: Chao Liu <chao.liu.zevorn@gmail.com>
1791
L: qemu-riscv@nongnu.org
1792
S: Maintained
1793
+F: docs/system/riscv/k230.rst
1794
F: hw/riscv/k230.c
1795
F: hw/watchdog/k230_wdt.c
1796
F: include/hw/riscv/k230.h
docs/system/riscv/k230.rst
new
+113
@@ -0,0 +1,113 @@
1
+Kendryte K230 virt reference platform (``k230``)
2
+==========================================================================
3
+The ``k230`` machine is compatible with the Kendryte K230 SDK.
4
+
5
+The K230 is a chip from the AIoT SoC series made by Kendryte ® — a part of
6
+Canaan Inc. It uses a brand-new multi-heterogeneous unit accelerated computing
7
+structure.
8
+
9
+This chip has 2 RISC-V computing cores and a new-generation KPU (Knowledge
10
+Process Unit) smart computing unit.
11
+
12
+For more information, see <https://www.kendryte.com/en/proDetail/230>
13
+
14
+Supported devices
15
+-----------------
16
+The ``k230`` machine supports the following devices:
17
+
18
+* 1 c908 cores (little core)
19
+* Core Local Interruptor (CLINT)
20
+* Platform-Level Interrupt Controller (PLIC)
21
+* 2 K230 Watchdog Timer
22
+* 5 UART
23
+
24
+Boot options
25
+------------
26
+The ``k230`` machine supports K230 SDK boot through M-mode U-Boot, which then
27
+starts OpenSBI/Linux with ``bootm``. It also supports direct Linux boot.
28
+
29
+K230 SDK Linux kernels use T-HEAD C9xx private MAEE page table attributes. QEMU
30
+does not implement MAEE in the generic RISC-V MMU, so such kernels need to be
31
+built with standard RISC-V PTE bits before they can boot under QEMU.
32
+
33
+Running
34
+-------
35
+
36
+Direct Linux boot
37
+~~~~~~~~~~~~~~~~~
38
+
39
+This flow lets QEMU load OpenSBI, Linux, initrd, and DTB directly, without
40
+running SDK U-Boot. The Linux Image must be rebuilt with standard RISC-V PTE
41
+bits before running under QEMU.
42
+
43
+.. code-block:: bash
44
+
45
+ $ SDK=k230_sdk/output/k230_canmv_defconfig
46
+ $ qemu-system-riscv64 -machine k230 \
47
+ -kernel "$SDK/images/little-core/Image" \
48
+ -dtb "/tmp/user-k230-qemu.dtb" \
49
+ -initrd "$SDK/images/little-core/rootfs.cpio.gz" \
50
+ -append "console=ttyS0,115200 earlycon=sbi cma=0" \
51
+ -nographic
52
+
53
+Direct boot uses the SDK little-core RAM layout for OpenSBI at
54
+``0x08000000``, Linux at ``0x08200000``, and the DTB at ``0x0a000000``. The
55
+initrd is placed by QEMU's generic RISC-V boot helper, and QEMU writes the
56
+initrd range and kernel command line into ``/chosen``. The DTB passed with
57
+``-dtb`` should be derived from ``$SDK/images/little-core/k230.dtb`` and must
58
+describe that initrd location as usable memory and disable any devices that are
59
+not emulated by this machine.
60
+
61
+U-Boot boot
62
+~~~~~~~~~~~
63
+
64
+This flow starts SDK U-Boot in M-mode with ``-bios``. Until the SDK storage
65
+path is modeled, place OpenSBI, Linux, initrd, and DTB in RAM with loader
66
+devices and run ``bootm`` manually. The Linux Image must be rebuilt with
67
+standard RISC-V PTE bits before running under QEMU.
68
+
69
+.. code-block:: bash
70
+
71
+ $ SDK=k230_sdk/output/k230_canmv_defconfig
72
+ $ IMAGE=$SDK/images/little-core/Image
73
+ $ INITRD=$SDK/images/little-core/rootfs.cpio.gz
74
+ $ DTB=$SDK/images/little-core/k230.dtb
75
+ $ FWJUMP_UIMAGE=/tmp/k230-fw-jump.uImage
76
+ $ INITRD_END=$(printf "0x%x" $((0x0a100000 + $(stat -c %s "$INITRD"))))
77
+ $ "$SDK/little/buildroot-ext/host/bin/mkimage" \
78
+ -A riscv -O linux -T kernel -C none \
79
+ -a 0x8000000 -e 0x8000000 -n opensbi \
80
+ -d "$SDK/images/little-core/fw_jump.bin" "$FWJUMP_UIMAGE"
81
+ $ qemu-system-riscv64 -machine k230 \
82
+ -bios "$SDK/little/uboot/u-boot" \
83
+ -device loader,file="$FWJUMP_UIMAGE",addr=0xc100000,force-raw=on \
84
+ -device loader,file="$IMAGE",addr=0x8200000,force-raw=on \
85
+ -device loader,file="$INITRD",addr=0xa100000,force-raw=on \
86
+ -device loader,file="$DTB",addr=0xa000000,force-raw=on \
87
+ -nographic
88
+
89
+The loader addresses mirror the SDK ``k230_canmv_defconfig`` output. Read the
90
+U-Boot addresses from the generated environment, and read the Linux RAM base
91
+from the generated ``hw/k230.dts.txt``. This replaces the SDK storage and
92
+decompression steps.
93
+
94
+Press Enter to stop autoboot. At the U-Boot prompt, run these commands:
95
+
96
+.. code-block:: bash
97
+
98
+ K230# setenv bootargs console=ttyS0,115200 earlycon=sbi cma=0
99
+ K230# fdt addr 0xa000000
100
+ K230# fdt resize 8192
101
+ K230# fdt set /chosen linux,initrd-start <0x0 0xa100000>
102
+ K230# fdt set /chosen linux,initrd-end <0x0 ${INITRD_END}>
103
+ K230# fdt set /soc/sdhci0@91580000 status disabled
104
+ K230# fdt set /soc/sdhci1@91581000 status disabled
105
+ K230# bootm 0xc100000 - 0xa000000
106
+
107
+Use ``setenv`` so ``bootm`` writes the kernel command line into
108
+``/chosen/bootargs``. The ``fdt`` commands select the loaded DTB, add space for
109
+edits, describe the initrd range in ``/chosen``, and disable SDHCI nodes because
110
+this machine does not emulate those controllers yet. Replace ``${INITRD_END}``
111
+with the host-calculated value above when typing the command. ``cma=0`` avoids
112
+the SDK kernel reserving too much of the little-core memory window for initramfs
113
+boot.
docs/system/target-riscv.rst
+1
@@ -66,6 +66,7 @@ undocumented; you can get a complete list by running
66
.. toctree::
67
:maxdepth: 1
68
69
+ riscv/k230
70
riscv/microblaze-v-generic
71
riscv/microchip-icicle-kit
72
riscv/mips