maix.rst 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414
  1. .. SPDX-License-Identifier: GPL-2.0+
  2. .. Copyright (C) 2020 Sean Anderson <seanga2@gmail.com>
  3. MAIX
  4. ====
  5. Several of the Sipeed Maix series of boards cotain the Kendryte K210 processor,
  6. a 64-bit RISC-V CPU. This processor contains several peripherals to accelerate
  7. neural network processing and other "ai" tasks. This includes a "KPU" neural
  8. network processor, an audio processor supporting beamforming reception, and a
  9. digital video port supporting capture and output at VGA resolution. Other
  10. peripherals include 8M of SRAM (accessible with and without caching); remappable
  11. pins, including 40 GPIOs; AES, FFT, and SHA256 accelerators; a DMA controller;
  12. and I2C, I2S, and SPI controllers. Maix peripherals vary, but include spi flash;
  13. on-board usb-serial bridges; ports for cameras, displays, and sd cards; and
  14. ESP32 chips.
  15. Currently, only the Sipeed MAIX BiT V2.0 (bitm) and Sipeed MAIXDUINO are
  16. supported, but the boards are fairly similar.
  17. Documentation for Maix boards is available from
  18. `Sipeed's website <http://dl.sipeed.com/MAIX/HDK/>`_.
  19. Documentation for the Kendryte K210 is available from
  20. `Kendryte's website <https://kendryte.com/downloads/>`_. However, hardware
  21. details are rather lacking, so most technical reference has been taken from the
  22. `standalone sdk <https://github.com/kendryte/kendryte-standalone-sdk>`_.
  23. Build and boot steps
  24. --------------------
  25. To build U-Boot, run
  26. .. code-block:: none
  27. make <defconfig>
  28. make CROSS_COMPILE=<your cross compile prefix>
  29. To flash U-Boot, run
  30. .. code-block:: none
  31. kflash -tp /dev/<your tty here> -B <board_id> u-boot-dtb.bin
  32. The board provides two serial devices, e.g.
  33. * /dev/serial/by-id/usb-Kongou_Hikari_Sipeed-Debug_12345678AB-if00-port0
  34. * /dev/serial/by-id/usb-Kongou_Hikari_Sipeed-Debug_12345678AB-if01-port0
  35. Which one is used for flashing depends on the board.
  36. Currently only a small subset of the board features are supported. So we can
  37. use the same default configuration and device tree. In the long run we may need
  38. separate settings.
  39. ======================== ========================== ========== ==========
  40. Board defconfig board_id TTY device
  41. ======================== ========================== ========== ==========
  42. Sipeed MAIX BiT sipeed_maix_bitm_defconfig bit first
  43. Sipeed MAIX BiT with Mic sipeed_maix_bitm_defconfig bit_mic first
  44. Sipeed MAIXDUINO sipeed_maix_bitm_defconfig maixduino first
  45. Sipeed MAIX GO goE second
  46. Sipeed MAIX ONE DOCK goD first
  47. ======================== ========================== ========== ==========
  48. Flashing causes a reboot of the device. Parameter -t specifies that the serial
  49. console shall be opened immediately. Boot output should look like the following:
  50. .. code-block:: none
  51. U-Boot 2020.04-rc2-00087-g2221cc09c1-dirty (Feb 28 2020 - 13:53:09 -0500)
  52. DRAM: 8 MiB
  53. In: serial@38000000
  54. Out: serial@38000000
  55. Err: serial@38000000
  56. =>
  57. OpenSBI
  58. ^^^^^^^
  59. OpenSBI is an open source supervisor execution environment implementing the
  60. RISC-V Supervisor Binary Interface Specification [1]. One of its features is
  61. to intercept run-time exceptions, e.g. for unaligned access or illegal
  62. instructions, and to emulate the failing instructions.
  63. The OpenSBI source can be downloaded via:
  64. .. code-block:: bash
  65. git clone https://github.com/riscv/opensbi
  66. As OpenSBI will be loaded at 0x80000000 we have to adjust the U-Boot text base.
  67. Furthermore we have to enable building U-Boot for S-mode::
  68. CONFIG_SYS_TEXT_BASE=0x80020000
  69. CONFIG_RISCV_SMODE=y
  70. Both settings are contained in sipeed_maix_smode_defconfig so we can build
  71. U-Boot with:
  72. .. code-block:: bash
  73. make sipeed_maix_smode_defconfig
  74. make
  75. To build OpenSBI with U-Boot as a payload:
  76. .. code-block:: bash
  77. cd opensbi
  78. make \
  79. PLATFORM=kendryte/k210 \
  80. FW_PAYLOAD=y \
  81. FW_PAYLOAD_OFFSET=0x20000 \
  82. FW_PAYLOAD_PATH=<path to U-Boot>/u-boot-dtb.bin
  83. The value of FW_PAYLOAD_OFFSET must match CONFIG_SYS_TEXT_BASE - 0x80000000.
  84. The file to flash is build/platform/kendryte/k210/firmware/fw_payload.bin.
  85. Loading Images
  86. ^^^^^^^^^^^^^^
  87. To load a kernel, transfer it over serial.
  88. .. code-block:: none
  89. => loady 80000000 1500000
  90. ## Switch baudrate to 1500000 bps and press ENTER ...
  91. *** baud: 1500000
  92. *** baud: 1500000 ***
  93. ## Ready for binary (ymodem) download to 0x80000000 at 1500000 bps...
  94. C
  95. *** file: loader.bin
  96. $ sz -vv loader.bin
  97. Sending: loader.bin
  98. Bytes Sent:2478208 BPS:72937
  99. Sending:
  100. Ymodem sectors/kbytes sent: 0/ 0k
  101. Transfer complete
  102. *** exit status: 0 ***
  103. ## Total Size = 0x0025d052 = 2478162 Bytes
  104. ## Switch baudrate to 115200 bps and press ESC ...
  105. *** baud: 115200
  106. *** baud: 115200 ***
  107. =>
  108. Running Programs
  109. ^^^^^^^^^^^^^^^^
  110. Binaries
  111. """"""""
  112. To run a bare binary, use the ``go`` command:
  113. .. code-block:: none
  114. => loady
  115. ## Ready for binary (ymodem) download to 0x80000000 at 115200 bps...
  116. C
  117. *** file: ./examples/standalone/hello_world.bin
  118. $ sz -vv ./examples/standalone/hello_world.bin
  119. Sending: hello_world.bin
  120. Bytes Sent: 4864 BPS:649
  121. Sending:
  122. Ymodem sectors/kbytes sent: 0/ 0k
  123. Transfer complete
  124. *** exit status: 0 ***
  125. (CAN) packets, 5 retries
  126. ## Total Size = 0x000012f8 = 4856 Bytes
  127. => go 80000000
  128. ## Starting application at 0x80000000 ...
  129. Example expects ABI version 9
  130. Actual U-Boot ABI version 9
  131. Hello World
  132. argc = 1
  133. argv[0] = "80000000"
  134. argv[1] = "<NULL>"
  135. Hit any key to exit ...
  136. Legacy Images
  137. """""""""""""
  138. To run legacy images, use the ``bootm`` command:
  139. .. code-block:: none
  140. $ tools/mkimage -A riscv -O u-boot -T standalone -C none -a 80000000 -e 80000000 -d examples/standalone/hello_world.bin hello_world.img
  141. Image Name:
  142. Created: Thu Mar 5 12:04:10 2020
  143. Image Type: RISC-V U-Boot Standalone Program (uncompressed)
  144. Data Size: 4856 Bytes = 4.74 KiB = 0.00 MiB
  145. Load Address: 80000000
  146. Entry Point: 80000000
  147. $ picocom -b 115200 /dev/ttyUSB0i
  148. => loady
  149. ## Ready for binary (ymodem) download to 0x80000000 at 115200 bps...
  150. C
  151. *** file: hello_world.img
  152. $ sz -vv hello_world.img
  153. Sending: hello_world.img
  154. Bytes Sent: 4992 BPS:665
  155. Sending:
  156. Ymodem sectors/kbytes sent: 0/ 0k
  157. Transfer complete
  158. *** exit status: 0 ***
  159. CAN) packets, 3 retries
  160. ## Total Size = 0x00001338 = 4920 Bytes
  161. => bootm
  162. ## Booting kernel from Legacy Image at 80000000 ...
  163. Image Name:
  164. Image Type: RISC-V U-Boot Standalone Program (uncompressed)
  165. Data Size: 4856 Bytes = 4.7 KiB
  166. Load Address: 80000000
  167. Entry Point: 80000000
  168. Verifying Checksum ... OK
  169. Loading Standalone Program
  170. Example expects ABI version 9
  171. Actual U-Boot ABI version 9
  172. Hello World
  173. argc = 0
  174. argv[0] = "<NULL>"
  175. Hit any key to exit ...
  176. Over- and Under-clocking
  177. ------------------------
  178. To change the clock speed of the K210, you will need to enable
  179. ``CONFIG_CLK_K210_SET_RATE`` and edit the board's device tree. To do this, add a
  180. section to ``arch/riscv/arch/riscv/dts/k210-maix-bit.dts`` like the following:
  181. .. code-block:: none
  182. &sysclk {
  183. assigned-clocks = <&sysclk K210_CLK_PLL0>;
  184. assigned-clock-rates = <800000000>;
  185. };
  186. There are three PLLs on the K210: PLL0 is the parent of most of the components,
  187. including the CPU and RAM. PLL1 is the parent of the neural network coprocessor.
  188. PLL2 is the parent of the sound processing devices. Note that child clocks of
  189. PLL0 and PLL2 run at *half* the speed of the PLLs. For example, if PLL0 is
  190. running at 800 MHz, then the CPU will run at 400 MHz. This is the example given
  191. above. The CPU can be overclocked to around 600 MHz, and underclocked to 26 MHz.
  192. It is possible to set PLL2's parent to PLL0. The plls are more accurate when
  193. converting between similar frequencies. This makes it easier to get an accurate
  194. frequency for I2S. As an example, consider sampling an I2S device at 44.1 kHz.
  195. On this device, the I2S serial clock runs at 64 times the sample rate.
  196. Therefore, we would like to run PLL2 at an even multiple of 2.8224 MHz. If
  197. PLL2's parent is IN0, we could use a frequency of 390 MHz (the same as the CPU's
  198. default speed). Dividing by 138 yields a serial clock of about 2.8261 MHz. This
  199. results in a sample rate of 44.158 kHz---around 50 Hz or .1% too fast. If,
  200. instead, we set PLL2's parent to PLL1 running at 390 MHz, and request a rate of
  201. 2.8224 * 136 = 383.8464 MHz, the achieved rate is 383.90625 MHz. Dividing by 136
  202. yields a serial clock of about 2.8228 MHz. This results in a sample rate of
  203. 44.107 kHz---just 7 Hz or .02% too fast. This configuration is shown in the
  204. following example:
  205. .. code-block:: none
  206. &sysclk {
  207. assigned-clocks = <&sysclk K210_CLK_PLL1>, <&sysclk K210_CLK_PLL2>;
  208. assigned-clock-parents = <0>, <&sysclk K210_CLK_PLL1>;
  209. assigned-clock-rates = <390000000>, <383846400>;
  210. };
  211. There are a couple of quirks to the PLLs. First, there are more frequency ratios
  212. just above and below 1.0, but there is a small gap around 1.0. To be explicit,
  213. if the input frequency is 100 MHz, it would be impossible to have an output of
  214. 99 or 101 MHz. In addition, there is a maximum frequency for the internal VCO,
  215. so higher input/output frequencies will be less accurate than lower ones.
  216. Technical Details
  217. -----------------
  218. Boot Sequence
  219. ^^^^^^^^^^^^^
  220. 1. ``RESET`` pin is deasserted.
  221. 2. Both harts begin executing at ``0x00001000``.
  222. 3. Both harts jump to firmware at ``0x88000000``.
  223. 4. One hart is chosen as a boot hart.
  224. 5. Firmware reads value of pin ``IO_16`` (ISP).
  225. * If the pin is low, enter ISP mode. This mode allows loading data to ram,
  226. writing it to flash, and booting from specific addresses.
  227. * If the pin is high, continue boot.
  228. 6. Firmware reads the next stage from flash (SPI3) to address ``0x80000000``.
  229. * If byte 0 is 1, the next stage is decrypted using the built-in AES
  230. accelerator and the one-time programmable, 128-bit AES key.
  231. * Bytes 1 to 4 hold the length of the next stage.
  232. * The SHA-256 sum of the next stage is automatically calculated, and verified
  233. against the 32 bytes following the next stage.
  234. 7. The boot hart sends an IPI to the other hart telling it to jump to the next
  235. stage.
  236. 8. The boot hart jumps to ``0x80000000``.
  237. Debug UART
  238. ^^^^^^^^^^
  239. The Debug UART is provided with the following settings::
  240. CONFIG_DEBUG_UART=y
  241. CONFIG_DEBUG_UART_SIFIVE=y
  242. CONFIG_DEBUG_UART_BASE=0x38000000
  243. CONFIG_DEBUG_UART_CLOCK=390000000
  244. Resetting the board
  245. ^^^^^^^^^^^^^^^^^^^
  246. The MAIX boards can be reset using the DTR and RTS lines of the serial console.
  247. How the lines are used depends on the specific board. See the code of kflash.py
  248. for details.
  249. This is the reset sequence for the MAXDUINO and MAIX BiT with Mic:
  250. .. code-block:: python
  251. def reset(self):
  252. self.device.setDTR(False)
  253. self.device.setRTS(False)
  254. time.sleep(0.1)
  255. self.device.setDTR(True)
  256. time.sleep(0.1)
  257. self.device.setDTR(False)
  258. time.sleep(0.1)
  259. and this for the MAIX Bit:
  260. .. code-block:: python
  261. def reset(self):
  262. self.device.setDTR(False)
  263. self.device.setRTS(False)
  264. time.sleep(0.1)
  265. self.device.setRTS(True)
  266. time.sleep(0.1)
  267. self.device.setRTS(False)
  268. time.sleep(0.1)
  269. Memory Map
  270. ^^^^^^^^^^
  271. ========== ========= ===========
  272. Address Size Description
  273. ========== ========= ===========
  274. 0x00000000 0x1000 debug
  275. 0x00001000 0x1000 rom
  276. 0x02000000 0xC000 clint
  277. 0x0C000000 0x4000000 plic
  278. 0x38000000 0x1000 uarths
  279. 0x38001000 0x1000 gpiohs
  280. 0x40000000 0x400000 sram0 (non-cached)
  281. 0x40400000 0x200000 sram1 (non-cached)
  282. 0x40600000 0x200000 airam (non-cached)
  283. 0x40800000 0xC00000 kpu
  284. 0x42000000 0x400000 fft
  285. 0x50000000 0x1000 dmac
  286. 0x50200000 0x200000 apb0
  287. 0x50200000 0x80 gpio
  288. 0x50210000 0x100 uart0
  289. 0x50220000 0x100 uart1
  290. 0x50230000 0x100 uart2
  291. 0x50240000 0x100 spi slave
  292. 0x50250000 0x200 i2s0
  293. 0x50250200 0x200 apu
  294. 0x50260000 0x200 i2s1
  295. 0x50270000 0x200 i2s2
  296. 0x50280000 0x100 i2c0
  297. 0x50290000 0x100 i2c1
  298. 0x502A0000 0x100 i2c2
  299. 0x502B0000 0x100 fpioa
  300. 0x502C0000 0x100 sha256
  301. 0x502D0000 0x100 timer0
  302. 0x502E0000 0x100 timer1
  303. 0x502F0000 0x100 timer2
  304. 0x50400000 0x200000 apb1
  305. 0x50400000 0x100 wdt0
  306. 0x50410000 0x100 wdt1
  307. 0x50420000 0x100 otp control
  308. 0x50430000 0x100 dvp
  309. 0x50440000 0x100 sysctl
  310. 0x50450000 0x100 aes
  311. 0x50460000 0x100 rtc
  312. 0x52000000 0x4000000 apb2
  313. 0x52000000 0x100 spi0
  314. 0x53000000 0x100 spi1
  315. 0x54000000 0x200 spi3
  316. 0x80000000 0x400000 sram0 (cached)
  317. 0x80400000 0x200000 sram1 (cached)
  318. 0x80600000 0x200000 airam (cached)
  319. 0x88000000 0x20000 otp
  320. 0x88000000 0xC200 firmware
  321. 0x8801C000 0x1000 riscv priv spec 1.9 config
  322. 0x8801D000 0x2000 flattened device tree (contains only addresses and
  323. interrupts)
  324. 0x8801f000 0x1000 credits
  325. ========== ========= ===========
  326. Links
  327. -----
  328. [1] https://github.com/riscv/riscv-sbi-doc
  329. RISC-V Supervisor Binary Interface Specification