1Sipeed MAIXDUINO Board
2======================
3
4The Sipeed MAIXDUINO board is a dual-core RISC-V 64-bits board based on the
5Canaan Kendryte K210 SoC. This board has the same form factor as the Arduino
6UNO board.
7
8Prerequisite
9------------
10
11In order to use the kflash utility to program this board, the user must have
12access to the board USB serial device file. The simplest way to do this is to
13add your user to the same group as this device file. Assume the device file is
14/dev/ttyUSB0, first identify the device group name. In most cases, it is
15either "dialout" or "uucp". Also verify that read-write access is enabled for
16the group:
17
18```
19$ ls -l /dev/ttyUSB0
20crw-rw---- 1 root dialout 188, 0 May 26 13:48 /dev/ttyUSB0
21```
22
23Then add yourself to that group (dialout in this example):
24
25```
26$ sudo usermod -a -G dialout $(whoami)
27```
28
29To enable the above, it is sometimes necessary to logout and login again.
30
31Buildroot Configuration
32-----------------------
33
34Two buildroot configurations are provided:
35
36(1) Direct Linux Kernel Boot
37
38This is defined by the sipeed_maixduino_defconfig configuration. This
39configuration allows building a bootable kernel image with a built-in initramfs
40root file system (the board SD card is not used). The built kernel image can be
41flashed directly to the board ROM for direct booting. No boot loader is
42required.
43
44(2) U-Boot SD-Card Boot
45
46The sipeed_maixduino_sdcard_defconfig configuration allows building a kernel
47image with the root file system on the board SD card. U-Boot is used as the
48boot loader.
49
50Note: U-Boot does not natively support the Sipeed MAIXDUINO board. However, the
51board and device tree differences with the Sipeed MAIX-bit board are small
52enough for U-Boot to work.
53
54Both configuration files will also compile and install the kflash and
55pyserial-miniterm host utilities to program bootable image files to the board
56and open a serial terminal console.
57
58Direct Linux Kernel Boot
59------------------------
60
61Using the sipeed_maixduino_defconfig configuration, the bootable kernel binary
62image is built as follows.
63
64```
65$ make sipeed_maixduino_defconfig
66$ make
67```
68
69The bootable binary image is the output/images/loader.bin file. This image file
70can be written to the board boot flash using the kflash utility.
71
72```
73$ output/host/bin/kflash -b 1500000 -p /dev/ttyUSB0 -t output/images/loader.bin
74```
75
76Once the kernel image file is fully programmed, a terminal console is open and
77the board can be rebooted by pressing the reset button on the board (if it does
78not reboot automatically).
79
80The output will be similar to the following.
81
82```
83[    0.000000] Linux version 5.18.0 (foo@bar.com) (riscv64-buildroot-linux-uclibc-gcc.br_real (Buildroot 2022.02-560-g6a2b542a09-dirty) 10.3.0, GNU ld (GNU Binutils) 2.32) #2 SMP Thu Apr 21 15:16:00 JST 2022
84[    0.000000] Machine model: SiPeed MAIXDUINO
85[    0.000000] earlycon: sifive0 at MMIO 0x0000000038000000 (options '115200n8')
86[    0.000000] printk: bootconsole [sifive0] enabled
87[    0.000000] Zone ranges:
88[    0.000000]   DMA32    [mem 0x0000000080000000-0x00000000807fffff]
89[    0.000000]   Normal   empty
90[    0.000000] Movable zone start for each node
91[    0.000000] Early memory node ranges
92[    0.000000]   node   0: [mem 0x0000000080000000-0x00000000807fffff]
93[    0.000000] Initmem setup node 0 [mem 0x0000000080000000-0x00000000807fffff]
94[    0.000000] riscv: ISA extensions acdfim
95[    0.000000] riscv: ELF capabilities acdfim
96[    0.000000] percpu: max_distance=0x16000 too large for vmalloc space 0x0
97[    0.000000] percpu: Embedded 11 pages/cpu s15264 r0 d29792 u45056
98[    0.000000] percpu: wasting 10 pages per chunk
99[    0.000000] Built 1 zonelists, mobility grouping off.  Total pages: 2020
100[    0.000000] Kernel command line: earlycon console=ttySIF0
101[    0.000000] Dentry cache hash table entries: 1024 (order: 1, 8192 bytes, linear)
102[    0.000000] Inode-cache hash table entries: 512 (order: 0, 4096 bytes, linear)
103[    0.000000] mem auto-init: stack:off, heap alloc:off, heap free:off
104[    0.000000] Memory: 6000K/8192K available (964K kernel code, 137K rwdata, 205K rodata, 530K init, 66K bss, 2192K reserved, 0K cma-reserved)
105[    0.000000] rcu: Hierarchical RCU implementation.
106[    0.000000] rcu: RCU calculated value of scheduler-enlistment delay is 25 jiffies.
107[    0.000000] NR_IRQS: 64, nr_irqs: 64, preallocated irqs: 0
108[    0.000000] riscv-intc: 64 local interrupts mapped
109[    0.000000] plic: interrupt-controller@c000000: mapped 65 interrupts with 2 handlers for 4 contexts.
110[    0.000000] k210-clk: clock-controller: CPU running at 390 MHz
111[    0.000000] clint: timer@2000000: timer running at 7800000 Hz
112[    0.000000] clocksource: clint_clocksource: mask: 0xffffffffffffffff max_cycles: 0x3990be68b, max_idle_ns: 881590404272 ns
113[    0.000001] sched_clock: 64 bits at 7MHz, resolution 128ns, wraps every 4398046511054ns
114[    0.008183] Calibrating delay loop (skipped), value calculated using timer frequency.. 15.60 BogoMIPS (lpj=31200)
115[    0.018249] pid_max: default: 4096 minimum: 301
116[    0.022860] Mount-cache hash table entries: 512 (order: 0, 4096 bytes, linear)
117[    0.029971] Mountpoint-cache hash table entries: 512 (order: 0, 4096 bytes, linear)
118[    0.040242] rcu: Hierarchical SRCU implementation.
119[    0.045124] smp: Bringing up secondary CPUs ...
120[    0.050217] smp: Brought up 1 node, 2 CPUs
121[    0.054346] devtmpfs: initialized
122[    0.070924] clocksource: jiffies: mask: 0xffffffff max_cycles: 0xffffffff, max_idle_ns: 7645041785100000 ns
123[    0.079996] pinctrl core: initialized pinctrl subsystem
124[    0.119893] clocksource: Switched to clocksource clint_clocksource
125[    0.131992] workingset: timestamp_bits=62 max_order=11 bucket_order=0
126[    0.179099] k210-sysctl 50440000.syscon: K210 system controller
127[    0.194904] k210-rst 50440000.syscon:reset-controller: K210 reset controller
128[    0.203108] cacheinfo: Unable to detect cache hierarchy for CPU 0
129[    0.213867] i2c_dev: i2c /dev entries driver
130[    0.223397] k210-fpioa 502b0000.pinmux: K210 FPIOA pin controller
131[    0.235632] 38000000.serial: ttySIF0 at MMIO 0x38000000 (irq = 1, base_baud = 115200) is a SiFive UART v0
132[    0.244585] printk: console [ttySIF0] enabled
133[    0.244585] printk: console [ttySIF0] enabled
134[    0.253190] printk: bootconsole [sifive0] disabled
135[    0.253190] printk: bootconsole [sifive0] disabled
136[    0.264820] panel@0 enforce active low on chipselect handle
137[    0.281482] Freeing unused kernel image (initmem) memory: 524K
138[    0.286621] This architecture does not have kernel memory protection.
139[    0.293047] Run /init as init process
140          __  _
141         / / (_) ____   _   _ __  __
142        / /  | ||  _ \ | | | |\ \/ /
143       / /___| || | | || |_| | >  <
144      /_____/|_||_| |_| \____|/_/\_\
145    64-bits RISC-V Kendryte K210 NOMMU
146
147/ #
148```
149
150To open a terminal console without re-flashing the board, the pyserial-miniterm
151host tool can be used.
152
153```
154$ output/host/bin/pyserial-miniterm --raw --eol=LF /dev/ttyUSB0 115200
155```
156
157The options "--raw" and "--eol=LF" are added here to avoid a double carriage
158return each time a command is entered.
159
160
161U-Boot SD-Card Boot
162-------------------
163
164The build procedure is similar to the built-in initramfs case.
165
166```
167$ make sipeed_maixduino_sdcard_defconfig
168$ make
169```
170
171The build process will generate two files under the output/images directory.
172
173* sdcard.img: The image file for the SD card filesystem. This image has 2
174  partitions. The first partition is a vfat partition containing the kernel
175  uImage and the board device tree binary. The second partition is the root
176  filesystem with busybox installed. The second partition is formatted using
177  ext2 (rev1).
178
179* uboot.bin: U-Boot bootable binary to load and boot the kernel from the SD
180  card.
181
182The SD card can be prepared by writing the sdcard.img file, as follows.
183
184```
185$ sudo dd if=output/images/sdcard.img of=/dev/sdX bs=1M
186$ sync
187$ eject /dev/sdX
188```
189
190Where /dev/sdX is the device file name of the SD card. Once completed, the SD
191card can be inserted into the board and the U-Boot binary image written to the
192board boot flash using the kflash utility.
193
194```
195$ output/host/bin/kflash -b 1500000 -p /dev/ttyUSB0 -t output/images/u-boot.bin
196```
197
198The above command will program U-Boot image to the board boot ROM and open a
199terminal console once the u-boot.bin file is fully programmed. Reboot into the
200newly programmed environment by pressing the board reset button.
201
202The output will be similar to the following.
203
204```
205[    0.000000] Linux version 5.18.0 (foo@bar.com) (riscv64-buildroot-linux-uclibc-gcc.br_real (Buildroot 2022.02-560-g6a2b542a09-dirty) 10.3.0, GNU ld (GNU Binutils) 2.32) #1 SMP Thu Apr 21 15:30:18 JST 2022
206[    0.000000] Machine model: SiPeed MAIXDUINO
207[    0.000000] earlycon: sifive0 at MMIO 0x0000000038000000 (options '115200n8')
208[    0.000000] printk: bootconsole [sifive0] enabled
209[    0.000000] Zone ranges:
210[    0.000000]   DMA32    [mem 0x0000000080000000-0x00000000807fffff]
211[    0.000000]   Normal   empty
212[    0.000000] Movable zone start for each node
213[    0.000000] Early memory node ranges
214[    0.000000]   node   0: [mem 0x0000000080000000-0x00000000807fffff]
215[    0.000000] Initmem setup node 0 [mem 0x0000000080000000-0x00000000807fffff]
216[    0.000000] riscv: ISA extensions acdfim
217[    0.000000] riscv: ELF capabilities acdfim
218[    0.000000] percpu: max_distance=0x16000 too large for vmalloc space 0x0
219[    0.000000] percpu: Embedded 11 pages/cpu s15392 r0 d29664 u45056
220[    0.000000] percpu: wasting 10 pages per chunk
221[    0.000000] Built 1 zonelists, mobility grouping off.  Total pages: 2020
222[    0.000000] Kernel command line: earlycon console=ttySIF0 root=/dev/mmcblk0p2 rootwait ro
223[    0.000000] Dentry cache hash table entries: 1024 (order: 1, 8192 bytes, linear)
224[    0.000000] Inode-cache hash table entries: 512 (order: 0, 4096 bytes, linear)
225[    0.000000] mem auto-init: stack:off, heap alloc:off, heap free:off
226[    0.000000] Memory: 6156K/8192K available (1180K kernel code, 151K rwdata, 239K rodata, 102K init, 69K bss, 2036K reserved, 0K cma-reserved)
227[    0.000000] rcu: Hierarchical RCU implementation.
228[    0.000000] rcu: RCU calculated value of scheduler-enlistment delay is 25 jiffies.
229[    0.000000] NR_IRQS: 64, nr_irqs: 64, preallocated irqs: 0
230[    0.000000] riscv-intc: 64 local interrupts mapped
231[    0.000000] plic: interrupt-controller@c000000: mapped 65 interrupts with 2 handlers for 4 contexts.
232[    0.000000] k210-clk: clock-controller: CPU running at 390 MHz
233[    0.000000] clint: timer@2000000: timer running at 7800000 Hz
234[    0.000000] clocksource: clint_clocksource: mask: 0xffffffffffffffff max_cycles: 0x3990be68b, max_idle_ns: 881590404272 ns
235[    0.000001] sched_clock: 64 bits at 7MHz, resolution 128ns, wraps every 4398046511054ns
236[    0.008191] Calibrating delay loop (skipped), value calculated using timer frequency.. 15.60 BogoMIPS (lpj=31200)
237[    0.018255] pid_max: default: 4096 minimum: 301
238[    0.022876] Mount-cache hash table entries: 512 (order: 0, 4096 bytes, linear)
239[    0.029982] Mountpoint-cache hash table entries: 512 (order: 0, 4096 bytes, linear)
240[    0.040417] rcu: Hierarchical SRCU implementation.
241[    0.045397] smp: Bringing up secondary CPUs ...
242[    0.050513] smp: Brought up 1 node, 2 CPUs
243[    0.054680] devtmpfs: initialized
244[    0.072127] clocksource: jiffies: mask: 0xffffffff max_cycles: 0xffffffff, max_idle_ns: 7645041785100000 ns
245[    0.081205] pinctrl core: initialized pinctrl subsystem
246[    0.125074] clocksource: Switched to clocksource clint_clocksource
247[    0.138311] workingset: timestamp_bits=62 max_order=11 bucket_order=0
248[    0.183471] k210-sysctl 50440000.syscon: K210 system controller
249[    0.199873] k210-rst 50440000.syscon:reset-controller: K210 reset controller
250[    0.208858] cacheinfo: Unable to detect cache hierarchy for CPU 0
251[    0.221586] i2c_dev: i2c /dev entries driver
252[    0.232786] k210-fpioa 502b0000.pinmux: K210 FPIOA pin controller
253[    0.246572] 38000000.serial: ttySIF0 at MMIO 0x38000000 (irq = 1, base_baud = 115200) is a SiFive UART v0
254[    0.255508] printk: console [ttySIF0] enabled
255[    0.255508] printk: console [ttySIF0] enabled
256[    0.264137] printk: bootconsole [sifive0] disabled
257[    0.264137] printk: bootconsole [sifive0] disabled
258[    0.275560] panel@0 enforce active low on chipselect handle
259[    0.313245] mmc_spi spi3.0: SD/MMC host mmc0, no WP, no poweroff, cd polling
260[    0.322845] Waiting for root device /dev/mmcblk0p2...
261[    0.345869] mmc0: host does not support reading read-only switch, assuming write-enable
262[    0.353221] mmc0: new SDHC card on SPI
263[    0.360233] mmcblk0: mmc0:0000 SA16G 14.5 GiB
264[    0.368350] random: fast init done
265[    0.372926]  mmcblk0: p1 p2
266[    0.391887] random: get_random_bytes called from 0x000000008009b7d2 with crng_init=1
267[    0.400427] VFS: Mounted root (ext2 filesystem) readonly on device 179:2.
268[    0.410128] devtmpfs: mounted
269[    0.412628] Freeing unused kernel image (initmem) memory: 96K
270[    0.418137] This architecture does not have kernel memory protection.
271[    0.424530] Run /sbin/init as init process
272[    0.563384] random: crng init done
273          __  _
274         / / (_) ____   _   _ __  __
275        / /  | ||  _ \ | | | |\ \/ /
276       / /___| || | | || |_| | >  <
277      /_____/|_||_| |_| \____|/_/\_\
278    64-bits RISC-V Kendryte K210 NOMMU
279
280/ #
281```
282
283Of note is that the kernel mounts the SD card as read-only by default to avoid
284corruptions of the ext2 root file system when the board is powered down. This
285is recommended as this board does not support clean shutdown or halt.
286
287Similarly to the initramfs build case, a console can be open without
288re-flashing the board using the host tool pyserial-miniterm.
289
290```
291$ output/host/bin/pyserial-miniterm --raw --eol=LF /dev/ttyUSB0 115200
292```
293