1Sipeed MAIX-Dock Board
2======================
3
4The Sipeed MAXI-Dock board is a dual-core RISC-V 64-bits board based on the
5Canaan Kendryte K210 SoC.
6
7Prerequisite
8------------
9
10In order to use the kflash utility to program this board, the user must have
11access to the board USB serial device file. The simplest way to do this is to
12add your user to the same group as this device file. Assume the device file is
13/dev/ttyUSB0, first identify the device group name. In most cases, it is
14either "dialout" or "uucp". Also verify that read-write access is enabled for
15the group:
16
17```
18$ ls -l /dev/ttyUSB0
19crw-rw---- 1 root dialout 188, 0 May 26 13:48 /dev/ttyUSB0
20```
21
22Then add yourself to that group (dialout in this example):
23
24```
25$ sudo usermod -a -G dialout $(whoami)
26```
27
28To enable the above, it is sometimes necessary to logout and login again.
29
30Buildroot Configuration
31-----------------------
32
33Two buildroot configuration files are provided:
34
35(1) Direct Linux Kernel Boot
36
37This is defined by the sipeed_maix_dock_defconfig configuration. This
38configuration allows building a bootable kernel image with a built-in initramfs
39root file system (the board SD card is not used). The built kernel image can be
40flashed directly to the board ROM for direct booting. No boot loader is
41required.
42
43(2) U-Boot SD-Card Boot
44
45The sipeed_maix_dock_sdcard_defconfig configuration allows building a kernel
46image with the root file system on the board SD card. U-Boot is used as the
47boot loader.
48
49Note: U-Boot does not natively support the Sipeed MAIX-Dock board. However, the
50board and device tree differences with the Sipeed MAIX-Bit board are small
51enough for U-Boot to work.
52
53Both configuration files will also compile the pyserial-miniterm host tool open
54a serial terminal console for the board.
55
56Direct Linux Kernel Boot
57-------------------------
58
59Using the sipeed_maix_dock_defconfig configuration, the bootable kernel binary
60image is built as follows.
61
62```
63$ make sipeed_maix_dock_defconfig
64$ make
65```
66
67Both configuration files will also compile and install the kflash and
68pyserial-miniterm host utilities to program bootable image files to the board
69and open a serial terminal console.
70
71```
72$ output/host/bin/kflash -b 1500000 -p /dev/ttyUSB0 -t output/images/loader.bin
73```
74
75Once the kernel image file is fully programmed, a terminal console is open and
76the board can be rebooted by pressing the reset button on the board (if it does
77not reboot automatically).
78
79The output will be similar to the following.
80
81```
82[ 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:47:42 JST 2022
83[ 0.000000] Machine model: SiPeed MAIX Dock
84[ 0.000000] earlycon: sifive0 at MMIO 0x0000000038000000 (options '115200n8')
85[ 0.000000] printk: bootconsole [sifive0] enabled
86[ 0.000000] Zone ranges:
87[ 0.000000] DMA32 [mem 0x0000000080000000-0x00000000807fffff]
88[ 0.000000] Normal empty
89[ 0.000000] Movable zone start for each node
90[ 0.000000] Early memory node ranges
91[ 0.000000] node 0: [mem 0x0000000080000000-0x00000000807fffff]
92[ 0.000000] Initmem setup node 0 [mem 0x0000000080000000-0x00000000807fffff]
93[ 0.000000] riscv: ISA extensions acdfim
94[ 0.000000] riscv: ELF capabilities acdfim
95[ 0.000000] percpu: max_distance=0x16000 too large for vmalloc space 0x0
96[ 0.000000] percpu: Embedded 11 pages/cpu s15264 r0 d29792 u45056
97[ 0.000000] percpu: wasting 10 pages per chunk
98[ 0.000000] Built 1 zonelists, mobility grouping off. Total pages: 2020
99[ 0.000000] Kernel command line: earlycon console=ttySIF0
100[ 0.000000] Dentry cache hash table entries: 1024 (order: 1, 8192 bytes, linear)
101[ 0.000000] Inode-cache hash table entries: 512 (order: 0, 4096 bytes, linear)
102[ 0.000000] mem auto-init: stack:off, heap alloc:off, heap free:off
103[ 0.000000] Memory: 5980K/8192K available (964K kernel code, 137K rwdata, 205K rodata, 546K init, 66K bss, 2212K reserved, 0K cma-reserved)
104[ 0.000000] rcu: Hierarchical RCU implementation.
105[ 0.000000] rcu: RCU calculated value of scheduler-enlistment delay is 25 jiffies.
106[ 0.000000] NR_IRQS: 64, nr_irqs: 64, preallocated irqs: 0
107[ 0.000000] riscv-intc: 64 local interrupts mapped
108[ 0.000000] plic: interrupt-controller@c000000: mapped 65 interrupts with 2 handlers for 4 contexts.
109[ 0.000000] k210-clk: clock-controller: CPU running at 390 MHz
110[ 0.000000] clint: timer@2000000: timer running at 7800000 Hz
111[ 0.000000] clocksource: clint_clocksource: mask: 0xffffffffffffffff max_cycles: 0x3990be68b, max_idle_ns: 881590404272 ns
112[ 0.000001] sched_clock: 64 bits at 7MHz, resolution 128ns, wraps every 4398046511054ns
113[ 0.008187] Calibrating delay loop (skipped), value calculated using timer frequency.. 15.60 BogoMIPS (lpj=31200)
114[ 0.018250] pid_max: default: 4096 minimum: 301
115[ 0.022859] Mount-cache hash table entries: 512 (order: 0, 4096 bytes, linear)
116[ 0.029971] Mountpoint-cache hash table entries: 512 (order: 0, 4096 bytes, linear)
117[ 0.040238] rcu: Hierarchical SRCU implementation.
118[ 0.045110] smp: Bringing up secondary CPUs ...
119[ 0.050215] smp: Brought up 1 node, 2 CPUs
120[ 0.054345] devtmpfs: initialized
121[ 0.071112] clocksource: jiffies: mask: 0xffffffff max_cycles: 0xffffffff, max_idle_ns: 7645041785100000 ns
122[ 0.080182] pinctrl core: initialized pinctrl subsystem
123[ 0.120689] clocksource: Switched to clocksource clint_clocksource
124[ 0.133165] workingset: timestamp_bits=62 max_order=11 bucket_order=0
125[ 0.181750] k210-sysctl 50440000.syscon: K210 system controller
126[ 0.198612] k210-rst 50440000.syscon:reset-controller: K210 reset controller
127[ 0.206644] cacheinfo: Unable to detect cache hierarchy for CPU 0
128[ 0.216569] i2c_dev: i2c /dev entries driver
129[ 0.225905] k210-fpioa 502b0000.pinmux: K210 FPIOA pin controller
130[ 0.238866] 38000000.serial: ttySIF0 at MMIO 0x38000000 (irq = 1, base_baud = 115200) is a SiFive UART v0
131[ 0.247778] printk: console [ttySIF0] enabled
132[ 0.247778] printk: console [ttySIF0] enabled
133[ 0.256459] printk: bootconsole [sifive0] disabled
134[ 0.256459] printk: bootconsole [sifive0] disabled
135[ 0.268225] panel@0 enforce active low on chipselect handle
136[ 0.285238] Freeing unused kernel image (initmem) memory: 540K
137[ 0.290372] This architecture does not have kernel memory protection.
138[ 0.296807] Run /init as init process
139 __ _
140 / / (_) ____ _ _ __ __
141 / / | || _ \ | | | |\ \/ /
142 / /___| || | | || |_| | > <
143 /_____/|_||_| |_| \____|/_/\_\
144 64-bits RISC-V Kendryte K210 NOMMU
145
146/ #
147```
148
149To open a terminal console without re-flashing the board, the pyserial-miniterm
150host tool can be used.
151
152```
153$ output/host/bin/pyserial-miniterm --raw --eol=LF /dev/ttyUSB0 115200
154```
155
156The options "--raw" and "--eol=LF" are added here to avoid a double carriage
157return each time a command is entered.
158
159
160U-Boot SD-Card Boot
161-------------------
162
163The build procedure is similar to the built-in initramfs case.
164
165```
166$ make sipeed_maix_dock_sdcard_defconfig
167$ make
168```
169
170The build process will generate two files under the output/images directory.
171
172* sdcard.img: The image file for the SD card filesystem. This image has 2
173 partitions. The first partition is a vfat partition containing the kernel
174 uImage and the board device tree binary. The second partition is the root
175 filesystem with busybox installed. The second partition is formatted using
176 ext2 (rev1).
177
178* uboot.bin: U-Boot bootable binary to load and boot the kernel from the SD
179 card.
180
181The SD card can be prepared by writing the sdcard.img file, as follows.
182
183```
184$ sudo dd if=output/images/sdcard.img of=/dev/sdX bs=1M
185$ sync
186$ eject /dev/sdX
187```
188
189Where /dev/sdX is the device file name of the SD card. Once completed, the SD
190card can be inserted into the board and the U-Boot binary image written to the
191board boot flash using the kflash utility.
192
193```
194$ output/host/bin/kflash -b 1500000 -p /dev/ttyUSB0 -t output/images/u-boot.bin
195```
196
197The above command will program U-Boot image to the board boot ROM and open a
198terminal console once the u-boot.bin file is fully programmed. Reboot into the
199newly programmed environment by pressing the board reset button if it does not
200reboot automatically.
201
202The output will be similar to the following.
203
204```
205U-Boot 2022.04 (Apr 21 2022 - 15:59:50 +0900)
206
207DRAM: 8 MiB
208Core: 34 devices, 17 uclasses, devicetree: separate
209WDT: Not starting watchdog@50400000
210MMC: spi@53000000:slot@0: 0
211Loading Environment from SPIFlash... SF: Detected w25q128fw with page size 256 Bytes, erase size 4 KiB, total 16 MiB
212*** Warning - bad CRC, using default environment
213
214In: serial@38000000
215Out: serial@38000000
216Err: serial@38000000
217Hit any key to stop autoboot: 0
2181717730 bytes read in 957 ms (1.7 MiB/s)
21910382 bytes read in 11 ms (920.9 KiB/s)
220## Booting kernel from Legacy Image at 80060000 ...
221 Image Name: Linux
222 Image Type: RISC-V Linux Kernel Image (uncompressed)
223 Data Size: 1717666 Bytes = 1.6 MiB
224 Load Address: 80000000
225 Entry Point: 80000000
226 Verifying Checksum ... OK
227## Flattened Device Tree blob at 80400000
228 Booting using the fdt blob at 0x80400000
229 Loading Kernel Image
230 Loading Device Tree to 00000000803fa000, end 00000000803ff88d ... OK
231
232Starting kernel ...
233
234[ 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 16:00:03 JST 2022
235[ 0.000000] Machine model: SiPeed MAIX Dock
236[ 0.000000] earlycon: sifive0 at MMIO 0x0000000038000000 (options '115200n8')
237[ 0.000000] printk: bootconsole [sifive0] enabled
238[ 0.000000] Zone ranges:
239[ 0.000000] DMA32 [mem 0x0000000080000000-0x00000000807fffff]
240[ 0.000000] Normal empty
241[ 0.000000] Movable zone start for each node
242[ 0.000000] Early memory node ranges
243[ 0.000000] node 0: [mem 0x0000000080000000-0x00000000807fffff]
244[ 0.000000] Initmem setup node 0 [mem 0x0000000080000000-0x00000000807fffff]
245[ 0.000000] riscv: ISA extensions acdfim
246[ 0.000000] riscv: ELF capabilities acdfim
247[ 0.000000] percpu: max_distance=0x16000 too large for vmalloc space 0x0
248[ 0.000000] percpu: Embedded 11 pages/cpu s15392 r0 d29664 u45056
249[ 0.000000] percpu: wasting 10 pages per chunk
250[ 0.000000] Built 1 zonelists, mobility grouping off. Total pages: 2020
251[ 0.000000] Kernel command line: earlycon console=ttySIF0 root=/dev/mmcblk0p2 rootwait ro
252[ 0.000000] Dentry cache hash table entries: 1024 (order: 1, 8192 bytes, linear)
253[ 0.000000] Inode-cache hash table entries: 512 (order: 0, 4096 bytes, linear)
254[ 0.000000] mem auto-init: stack:off, heap alloc:off, heap free:off
255[ 0.000000] Memory: 6156K/8192K available (1180K kernel code, 151K rwdata, 239K rodata, 102K init, 69K bss, 2036K reserved, 0K cma-reserved)
256[ 0.000000] rcu: Hierarchical RCU implementation.
257[ 0.000000] rcu: RCU calculated value of scheduler-enlistment delay is 25 jiffies.
258[ 0.000000] NR_IRQS: 64, nr_irqs: 64, preallocated irqs: 0
259[ 0.000000] riscv-intc: 64 local interrupts mapped
260[ 0.000000] plic: interrupt-controller@c000000: mapped 65 interrupts with 2 handlers for 4 contexts.
261[ 0.000000] k210-clk: clock-controller: CPU running at 390 MHz
262[ 0.000000] clint: timer@2000000: timer running at 7800000 Hz
263[ 0.000000] clocksource: clint_clocksource: mask: 0xffffffffffffffff max_cycles: 0x3990be68b, max_idle_ns: 881590404272 ns
264[ 0.000001] sched_clock: 64 bits at 7MHz, resolution 128ns, wraps every 4398046511054ns
265[ 0.008196] Calibrating delay loop (skipped), value calculated using timer frequency.. 15.60 BogoMIPS (lpj=31200)
266[ 0.018256] pid_max: default: 4096 minimum: 301
267[ 0.022876] Mount-cache hash table entries: 512 (order: 0, 4096 bytes, linear)
268[ 0.029980] Mountpoint-cache hash table entries: 512 (order: 0, 4096 bytes, linear)
269[ 0.040401] rcu: Hierarchical SRCU implementation.
270[ 0.045379] smp: Bringing up secondary CPUs ...
271[ 0.050494] smp: Brought up 1 node, 2 CPUs
272[ 0.054656] devtmpfs: initialized
273[ 0.072338] clocksource: jiffies: mask: 0xffffffff max_cycles: 0xffffffff, max_idle_ns: 7645041785100000 ns
274[ 0.081415] pinctrl core: initialized pinctrl subsystem
275[ 0.123902] clocksource: Switched to clocksource clint_clocksource
276[ 0.136898] workingset: timestamp_bits=62 max_order=11 bucket_order=0
277[ 0.182570] k210-sysctl 50440000.syscon: K210 system controller
278[ 0.198158] k210-rst 50440000.syscon:reset-controller: K210 reset controller
279[ 0.207473] cacheinfo: Unable to detect cache hierarchy for CPU 0
280[ 0.219724] i2c_dev: i2c /dev entries driver
281[ 0.230080] k210-fpioa 502b0000.pinmux: K210 FPIOA pin controller
282[ 0.243091] 38000000.serial: ttySIF0 at MMIO 0x38000000 (irq = 1, base_baud = 115200) is a SiFive UART v0
283[ 0.252034] printk: console [ttySIF0] enabled
284[ 0.252034] printk: console [ttySIF0] enabled
285[ 0.260656] printk: bootconsole [sifive0] disabled
286[ 0.260656] printk: bootconsole [sifive0] disabled
287[ 0.272546] panel@0 enforce active low on chipselect handle
288[ 0.308098] mmc_spi spi3.0: SD/MMC host mmc0, no WP, no poweroff, cd polling
289[ 0.320197] Waiting for root device /dev/mmcblk0p2...
290[ 0.344667] mmc0: host does not support reading read-only switch, assuming write-enable
291[ 0.352020] mmc0: new SDHC card on SPI
292[ 0.358566] mmcblk0: mmc0:0000 SA16G 14.5 GiB
293[ 0.366866] random: fast init done
294[ 0.371439] mmcblk0: p1 p2
295[ 0.391314] random: get_random_bytes called from 0x000000008009b7d2 with crng_init=1
296[ 0.400977] VFS: Mounted root (ext2 filesystem) readonly on device 179:2.
297[ 0.410966] devtmpfs: mounted
298[ 0.413521] Freeing unused kernel image (initmem) memory: 96K
299[ 0.418944] This architecture does not have kernel memory protection.
300[ 0.425370] Run /sbin/init as init process
301[ 0.633502] random: crng init done
302 __ _
303 / / (_) ____ _ _ __ __
304 / / | || _ \ | | | |\ \/ /
305 / /___| || | | || |_| | > <
306 /_____/|_||_| |_| \____|/_/\_\
307 64-bits RISC-V Kendryte K210 NOMMU
308
309/ #
310```
311
312Of note is that the kernel mounts the SD card as read-only by default to avoid
313corruptions of the ext2 root file system when the board is powered down. This
314is recommended as this board does not support clean shutdown or halt.
315
316Similarly to the initramfs build case, a console can be open without
317re-flashing the board using the host tool pyserial-miniterm.
318
319```
320$ output/host/bin/pyserial-miniterm --raw --eol=LF /dev/ttyUSB0 115200
321```
322