doc/board/sipeed/maix.rst

   1 .. SPDX-License-Identifier: GPL-2.0+
   2 .. Copyright (C) 2020 Sean Anderson <seanga2@gmail.com>
   3
   4 MAIX
   5 ====
   6
   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
  16 ESP32 chips.
  17
  18 Currently, only the Sipeed MAIX BiT V2.0 (bitm) and Sipeed MAIXDUINO are
  19 supported, but the boards are fairly similar.
  20
  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>`_.
  27
  28 Build and boot steps
  29 --------------------
  30
  31 To build U-Boot, run
  32
  33 .. code-block:: none
  34
  35     make <defconfig>
  36     make CROSS_COMPILE=<your cross compile prefix>
  37
  38 To flash U-Boot, run
  39
  40 .. code-block:: none
  41
  42     kflash -tp /dev/<your tty here> -B <board_id> u-boot-dtb.bin
  43
  44 The board provides two serial devices, e.g.
  45
  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
  48
  49 Which one is used for flashing depends on the board.
  50
  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
  53 separate settings.
  54
  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 ======================== ========================== ========== ==========
  64
  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:
  67
  68 .. code-block:: none
  69
  70     U-Boot 2020.04-rc2-00087-g2221cc09c1-dirty (Feb 28 2020 - 13:53:09 -0500)
  71
  72     DRAM:  8 MiB
  73     In:    serial@38000000
  74     Out:   serial@38000000
  75     Err:   serial@38000000
  76     =>
  77
  78 OpenSBI
  79 ^^^^^^^
  80
  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.
  85
  86 The OpenSBI source can be downloaded via:
  87
  88 .. code-block:: bash
  89
  90     git clone https://github.com/riscv/opensbi
  91
  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::
  94
  95     CONFIG_SYS_TEXT_BASE=0x80020000
  96     CONFIG_RISCV_SMODE=y
  97
  98 Both settings are contained in sipeed_maix_smode_defconfig so we can build
  99 U-Boot with:
 100
 101 .. code-block:: bash
 102
 103     make sipeed_maix_smode_defconfig
 104     make
 105
 106 To build OpenSBI with U-Boot as a payload:
 107
 108 .. code-block:: bash
 109
 110     cd opensbi
 111     make \
 112     PLATFORM=kendryte/k210 \
 113     FW_PAYLOAD=y \
 114     FW_PAYLOAD_OFFSET=0x20000 \
 115     FW_PAYLOAD_PATH=<path to U-Boot>/u-boot-dtb.bin
 116
 117 The value of FW_PAYLOAD_OFFSET must match CONFIG_SYS_TEXT_BASE - 0x80000000.
 118
 119 The file to flash is build/platform/kendryte/k210/firmware/fw_payload.bin.
 120
 121 Loading Images
 122 ^^^^^^^^^^^^^^
 123
 124 To load a kernel, transfer it over serial.
 125
 126 .. code-block:: none
 127
 128     => loady 80000000 1500000
 129     ## Switch baudrate to 1500000 bps and press ENTER ...
 130
 131     *** baud: 1500000
 132
 133     *** baud: 1500000 ***
 134     ## Ready for binary (ymodem) download to 0x80000000 at 1500000 bps...
 135     C
 136     *** file: loader.bin
 137     $ sz -vv loader.bin
 138     Sending: loader.bin
 139     Bytes Sent:2478208   BPS:72937
 140     Sending:
 141     Ymodem sectors/kbytes sent:   0/ 0k
 142     Transfer complete
 143
 144     *** exit status: 0 ***
 145     ## Total Size      = 0x0025d052 = 2478162 Bytes
 146     ## Switch baudrate to 115200 bps and press ESC ...
 147
 148     *** baud: 115200
 149
 150     *** baud: 115200 ***
 151     =>
 152
 153 Running Programs
 154 ^^^^^^^^^^^^^^^^
 155
 156 Binaries
 157 """"""""
 158
 159 To run a bare binary, use the ``go`` command:
 160
 161 .. code-block:: none
 162
 163     => loady
 164     ## Ready for binary (ymodem) download to 0x80000000 at 115200 bps...
 165     C
 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
 170     Sending:
 171     Ymodem sectors/kbytes sent:   0/ 0k
 172     Transfer complete
 173
 174     *** exit status: 0 ***
 175     (CAN) packets, 5 retries
 176     ## Total Size      = 0x000012f8 = 4856 Bytes
 177     => go 80000000
 178     ## Starting application at 0x80000000 ...
 179     Example expects ABI version 9
 180     Actual U-Boot ABI version 9
 181     Hello World
 182     argc = 1
 183     argv[0] = "80000000"
 184     argv[1] = "<NULL>"
 185     Hit any key to exit ...
 186
 187 Legacy Images
 188 """""""""""""
 189
 190 To run legacy images, use the ``bootm`` command:
 191
 192 .. code-block:: none
 193
 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
 195     Image Name:
 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
 201
 202     $ picocom -b 115200 /dev/ttyUSB0i
 203     => loady
 204     ## Ready for binary (ymodem) download to 0x80000000 at 115200 bps...
 205     C
 206     *** file: hello_world.img
 207     $ sz -vv hello_world.img
 208     Sending: hello_world.img
 209     Bytes Sent:   4992   BPS:665
 210     Sending:
 211     Ymodem sectors/kbytes sent:   0/ 0k
 212     Transfer complete
 213
 214     *** exit status: 0 ***
 215     CAN) packets, 3 retries
 216     ## Total Size      = 0x00001338 = 4920 Bytes
 217     => bootm
 218     ## Booting kernel from Legacy Image at 80000000 ...
 219        Image Name:
 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
 228     Hello World
 229     argc = 0
 230     argv[0] = "<NULL>"
 231     Hit any key to exit ...
 232
 233 Over- and Under-clocking
 234 ------------------------
 235
 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:
 239
 240 .. code-block:: none
 241
 242     &sysclk {
 243         assigned-clocks = <&sysclk K210_CLK_PLL0>;
 244         assigned-clock-rates = <800000000>;
 245     };
 246
 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.
 253
 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
 266 following example:
 267
 268 .. code-block:: none
 269
 270     &sysclk {
 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>;
 274     };
 275
 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.
 281
 282 Technical Details
 283 -----------------
 284
 285 Boot Sequence
 286 ^^^^^^^^^^^^^
 287
 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).
 293
 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``.
 298
 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
 305    stage.
 306 8. The boot hart jumps to ``0x80000000``.
 307
 308 Debug UART
 309 ^^^^^^^^^^
 310
 311 The Debug UART is provided with the following settings::
 312
 313     CONFIG_DEBUG_UART=y
 314     CONFIG_DEBUG_UART_SIFIVE=y
 315     CONFIG_DEBUG_UART_BASE=0x38000000
 316     CONFIG_DEBUG_UART_CLOCK=390000000
 317
 318 Resetting the board
 319 ^^^^^^^^^^^^^^^^^^^
 320
 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
 323 for details.
 324
 325 This is the reset sequence for the MAXDUINO and MAIX BiT with Mic:
 326
 327 .. code-block:: python
 328
 329    def reset(self):
 330         self.device.setDTR(False)
 331         self.device.setRTS(False)
 332         time.sleep(0.1)
 333         self.device.setDTR(True)
 334         time.sleep(0.1)
 335         self.device.setDTR(False)
 336         time.sleep(0.1)
 337
 338 and this for the MAIX Bit:
 339
 340 .. code-block:: python
 341
 342    def reset(self):
 343         self.device.setDTR(False)
 344         self.device.setRTS(False)
 345         time.sleep(0.1)
 346         self.device.setRTS(True)
 347         time.sleep(0.1)
 348         self.device.setRTS(False)
 349         time.sleep(0.1)
 350
 351 Memory Map
 352 ^^^^^^^^^^
 353
 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
 370 0x50200000 0x80      gpio
 371 0x50210000 0x100     uart0
 372 0x50220000 0x100     uart1
 373 0x50230000 0x100     uart2
 374 0x50240000 0x100     spi slave
 375 0x50250000 0x200     i2s0
 376 0x50250200 0x200     apu
 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
 391 0x50430000 0x100     dvp
 392 0x50440000 0x100     sysctl
 393 0x50450000 0x100     aes
 394 0x50460000 0x100     rtc
 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
 406                      interrupts)
 407 0x8801f000 0x1000    credits
 408 ========== ========= ===========
 409
 410 Links
 411 -----
 412
 413 [1] https://github.com/riscv/riscv-sbi-doc
 414     RISC-V Supervisor Binary Interface Specification