1 .. SPDX-License-Identifier: GPL-2.0+
2 .. Copyright (C) 2020 Sean Anderson <seanga2@gmail.com>
7 Several of the Sipeed Maix series of boards cotain the Kendryte K210 processor,
8 a 64-bit RISC-V CPU. This processor contains several peripherals to accelerate
9 neural network processing and other "ai" tasks. This includes a "KPU" neural
10 network processor, an audio processor supporting beamforming reception, and a
11 digital video port supporting capture and output at VGA resolution. Other
12 peripherals include 8M of SRAM (accessible with and without caching); remappable
13 pins, including 40 GPIOs; AES, FFT, and SHA256 accelerators; a DMA controller;
14 and I2C, I2S, and SPI controllers. Maix peripherals vary, but include spi flash;
15 on-board usb-serial bridges; ports for cameras, displays, and sd cards; and
18 Currently, only the Sipeed MAIX BiT V2.0 (bitm) and Sipeed MAIXDUINO are
19 supported, but the boards are fairly similar.
21 Documentation for Maix boards is available from
22 `Sipeed's website <http://dl.sipeed.com/MAIX/HDK/>`_.
23 Documentation for the Kendryte K210 is available from
24 `Kendryte's website <https://kendryte.com/downloads/>`_. However, hardware
25 details are rather lacking, so most technical reference has been taken from the
26 `standalone sdk <https://github.com/kendryte/kendryte-standalone-sdk>`_.
36 make CROSS_COMPILE=<your cross compile prefix>
42 kflash -tp /dev/<your tty here> -B <board_id> u-boot-dtb.bin
44 The board provides two serial devices, e.g.
46 * /dev/serial/by-id/usb-Kongou_Hikari_Sipeed-Debug_12345678AB-if00-port0
47 * /dev/serial/by-id/usb-Kongou_Hikari_Sipeed-Debug_12345678AB-if01-port0
49 Which one is used for flashing depends on the board.
51 Currently only a small subset of the board features are supported. So we can
52 use the same default configuration and device tree. In the long run we may need
55 ======================== ========================== ========== ==========
56 Board defconfig board_id TTY device
57 ======================== ========================== ========== ==========
58 Sipeed MAIX BiT sipeed_maix_bitm_defconfig bit first
59 Sipeed MAIX BiT with Mic sipeed_maix_bitm_defconfig bit_mic first
60 Sipeed MAIXDUINO sipeed_maix_bitm_defconfig maixduino first
61 Sipeed MAIX GO goE second
62 Sipeed MAIX ONE DOCK goD first
63 ======================== ========================== ========== ==========
65 Flashing causes a reboot of the device. Parameter -t specifies that the serial
66 console shall be opened immediately. Boot output should look like the following:
70 U-Boot 2020.04-rc2-00087-g2221cc09c1-dirty (Feb 28 2020 - 13:53:09 -0500)
81 OpenSBI is an open source supervisor execution environment implementing the
82 RISC-V Supervisor Binary Interface Specification [1]. One of its features is
83 to intercept run-time exceptions, e.g. for unaligned access or illegal
84 instructions, and to emulate the failing instructions.
86 The OpenSBI source can be downloaded via:
90 git clone https://github.com/riscv/opensbi
92 As OpenSBI will be loaded at 0x80000000 we have to adjust the U-Boot text base.
93 Furthermore we have to enable building U-Boot for S-mode::
95 CONFIG_SYS_TEXT_BASE=0x80020000
98 Both settings are contained in sipeed_maix_smode_defconfig so we can build
103 make sipeed_maix_smode_defconfig
106 To build OpenSBI with U-Boot as a payload:
112 PLATFORM=kendryte/k210 \
114 FW_PAYLOAD_OFFSET=0x20000 \
115 FW_PAYLOAD_PATH=<path to U-Boot>/u-boot-dtb.bin
117 The value of FW_PAYLOAD_OFFSET must match CONFIG_SYS_TEXT_BASE - 0x80000000.
119 The file to flash is build/platform/kendryte/k210/firmware/fw_payload.bin.
124 To load a kernel, transfer it over serial.
128 => loady 80000000 1500000
129 ## Switch baudrate to 1500000 bps and press ENTER ...
133 *** baud: 1500000 ***
134 ## Ready for binary (ymodem) download to 0x80000000 at 1500000 bps...
139 Bytes Sent:2478208 BPS:72937
141 Ymodem sectors/kbytes sent: 0/ 0k
144 *** exit status: 0 ***
145 ## Total Size = 0x0025d052 = 2478162 Bytes
146 ## Switch baudrate to 115200 bps and press ESC ...
159 To run a bare binary, use the ``go`` command:
164 ## Ready for binary (ymodem) download to 0x80000000 at 115200 bps...
166 *** file: ./examples/standalone/hello_world.bin
167 $ sz -vv ./examples/standalone/hello_world.bin
168 Sending: hello_world.bin
169 Bytes Sent: 4864 BPS:649
171 Ymodem sectors/kbytes sent: 0/ 0k
174 *** exit status: 0 ***
175 (CAN) packets, 5 retries
176 ## Total Size = 0x000012f8 = 4856 Bytes
178 ## Starting application at 0x80000000 ...
179 Example expects ABI version 9
180 Actual U-Boot ABI version 9
185 Hit any key to exit ...
190 To run legacy images, use the ``bootm`` command:
194 $ tools/mkimage -A riscv -O u-boot -T standalone -C none -a 80000000 -e 80000000 -d examples/standalone/hello_world.bin hello_world.img
196 Created: Thu Mar 5 12:04:10 2020
197 Image Type: RISC-V U-Boot Standalone Program (uncompressed)
198 Data Size: 4856 Bytes = 4.74 KiB = 0.00 MiB
199 Load Address: 80000000
200 Entry Point: 80000000
202 $ picocom -b 115200 /dev/ttyUSB0i
204 ## Ready for binary (ymodem) download to 0x80000000 at 115200 bps...
206 *** file: hello_world.img
207 $ sz -vv hello_world.img
208 Sending: hello_world.img
209 Bytes Sent: 4992 BPS:665
211 Ymodem sectors/kbytes sent: 0/ 0k
214 *** exit status: 0 ***
215 CAN) packets, 3 retries
216 ## Total Size = 0x00001338 = 4920 Bytes
218 ## Booting kernel from Legacy Image at 80000000 ...
220 Image Type: RISC-V U-Boot Standalone Program (uncompressed)
221 Data Size: 4856 Bytes = 4.7 KiB
222 Load Address: 80000000
223 Entry Point: 80000000
224 Verifying Checksum ... OK
225 Loading Standalone Program
226 Example expects ABI version 9
227 Actual U-Boot ABI version 9
231 Hit any key to exit ...
233 Over- and Under-clocking
234 ------------------------
236 To change the clock speed of the K210, you will need to enable
237 ``CONFIG_CLK_K210_SET_RATE`` and edit the board's device tree. To do this, add a
238 section to ``arch/riscv/arch/riscv/dts/k210-maix-bit.dts`` like the following:
243 assigned-clocks = <&sysclk K210_CLK_PLL0>;
244 assigned-clock-rates = <800000000>;
247 There are three PLLs on the K210: PLL0 is the parent of most of the components,
248 including the CPU and RAM. PLL1 is the parent of the neural network coprocessor.
249 PLL2 is the parent of the sound processing devices. Note that child clocks of
250 PLL0 and PLL2 run at *half* the speed of the PLLs. For example, if PLL0 is
251 running at 800 MHz, then the CPU will run at 400 MHz. This is the example given
252 above. The CPU can be overclocked to around 600 MHz, and underclocked to 26 MHz.
254 It is possible to set PLL2's parent to PLL0. The plls are more accurate when
255 converting between similar frequencies. This makes it easier to get an accurate
256 frequency for I2S. As an example, consider sampling an I2S device at 44.1 kHz.
257 On this device, the I2S serial clock runs at 64 times the sample rate.
258 Therefore, we would like to run PLL2 at an even multiple of 2.8224 MHz. If
259 PLL2's parent is IN0, we could use a frequency of 390 MHz (the same as the CPU's
260 default speed). Dividing by 138 yields a serial clock of about 2.8261 MHz. This
261 results in a sample rate of 44.158 kHz---around 50 Hz or .1% too fast. If,
262 instead, we set PLL2's parent to PLL1 running at 390 MHz, and request a rate of
263 2.8224 * 136 = 383.8464 MHz, the achieved rate is 383.90625 MHz. Dividing by 136
264 yields a serial clock of about 2.8228 MHz. This results in a sample rate of
265 44.107 kHz---just 7 Hz or .02% too fast. This configuration is shown in the
271 assigned-clocks = <&sysclk K210_CLK_PLL1>, <&sysclk K210_CLK_PLL2>;
272 assigned-clock-parents = <0>, <&sysclk K210_CLK_PLL1>;
273 assigned-clock-rates = <390000000>, <383846400>;
276 There are a couple of quirks to the PLLs. First, there are more frequency ratios
277 just above and below 1.0, but there is a small gap around 1.0. To be explicit,
278 if the input frequency is 100 MHz, it would be impossible to have an output of
279 99 or 101 MHz. In addition, there is a maximum frequency for the internal VCO,
280 so higher input/output frequencies will be less accurate than lower ones.
288 1. ``RESET`` pin is deasserted.
289 2. Both harts begin executing at ``0x00001000``.
290 3. Both harts jump to firmware at ``0x88000000``.
291 4. One hart is chosen as a boot hart.
292 5. Firmware reads value of pin ``IO_16`` (ISP).
294 * If the pin is low, enter ISP mode. This mode allows loading data to ram,
295 writing it to flash, and booting from specific addresses.
296 * If the pin is high, continue boot.
297 6. Firmware reads the next stage from flash (SPI3) to address ``0x80000000``.
299 * If byte 0 is 1, the next stage is decrypted using the built-in AES
300 accelerator and the one-time programmable, 128-bit AES key.
301 * Bytes 1 to 4 hold the length of the next stage.
302 * The SHA-256 sum of the next stage is automatically calculated, and verified
303 against the 32 bytes following the next stage.
304 7. The boot hart sends an IPI to the other hart telling it to jump to the next
306 8. The boot hart jumps to ``0x80000000``.
311 The Debug UART is provided with the following settings::
314 CONFIG_DEBUG_UART_SIFIVE=y
315 CONFIG_DEBUG_UART_BASE=0x38000000
316 CONFIG_DEBUG_UART_CLOCK=390000000
321 The MAIX boards can be reset using the DTR and RTS lines of the serial console.
322 How the lines are used depends on the specific board. See the code of kflash.py
325 This is the reset sequence for the MAXDUINO and MAIX BiT with Mic:
327 .. code-block:: python
330 self.device.setDTR(False)
331 self.device.setRTS(False)
333 self.device.setDTR(True)
335 self.device.setDTR(False)
338 and this for the MAIX Bit:
340 .. code-block:: python
343 self.device.setDTR(False)
344 self.device.setRTS(False)
346 self.device.setRTS(True)
348 self.device.setRTS(False)
354 ========== ========= ===========
355 Address Size Description
356 ========== ========= ===========
357 0x00000000 0x1000 debug
358 0x00001000 0x1000 rom
359 0x02000000 0xC000 clint
360 0x0C000000 0x4000000 plic
361 0x38000000 0x1000 uarths
362 0x38001000 0x1000 gpiohs
363 0x40000000 0x400000 sram0 (non-cached)
364 0x40400000 0x200000 sram1 (non-cached)
365 0x40600000 0x200000 airam (non-cached)
366 0x40800000 0xC00000 kpu
367 0x42000000 0x400000 fft
368 0x50000000 0x1000 dmac
369 0x50200000 0x200000 apb0
371 0x50210000 0x100 uart0
372 0x50220000 0x100 uart1
373 0x50230000 0x100 uart2
374 0x50240000 0x100 spi slave
375 0x50250000 0x200 i2s0
377 0x50260000 0x200 i2s1
378 0x50270000 0x200 i2s2
379 0x50280000 0x100 i2c0
380 0x50290000 0x100 i2c1
381 0x502A0000 0x100 i2c2
382 0x502B0000 0x100 fpioa
383 0x502C0000 0x100 sha256
384 0x502D0000 0x100 timer0
385 0x502E0000 0x100 timer1
386 0x502F0000 0x100 timer2
387 0x50400000 0x200000 apb1
388 0x50400000 0x100 wdt0
389 0x50410000 0x100 wdt1
390 0x50420000 0x100 otp control
392 0x50440000 0x100 sysctl
395 0x52000000 0x4000000 apb2
396 0x52000000 0x100 spi0
397 0x53000000 0x100 spi1
398 0x54000000 0x200 spi3
399 0x80000000 0x400000 sram0 (cached)
400 0x80400000 0x200000 sram1 (cached)
401 0x80600000 0x200000 airam (cached)
402 0x88000000 0x20000 otp
403 0x88000000 0xC200 firmware
404 0x8801C000 0x1000 riscv priv spec 1.9 config
405 0x8801D000 0x2000 flattened device tree (contains only addresses and
407 0x8801f000 0x1000 credits
408 ========== ========= ===========
413 [1] https://github.com/riscv/riscv-sbi-doc
414 RISC-V Supervisor Binary Interface Specification