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 Loading Images
  79 ^^^^^^^^^^^^^^
  80
  81 To load a kernel, transfer it over serial.
  82
  83 .. code-block:: none
  84
  85     => loady 80000000 1500000
  86     ## Switch baudrate to 1500000 bps and press ENTER ...
  87
  88     *** baud: 1500000
  89
  90     *** baud: 1500000 ***
  91     ## Ready for binary (ymodem) download to 0x80000000 at 1500000 bps...
  92     C
  93     *** file: loader.bin
  94     $ sz -vv loader.bin
  95     Sending: loader.bin
  96     Bytes Sent:2478208   BPS:72937
  97     Sending:
  98     Ymodem sectors/kbytes sent:   0/ 0k
  99     Transfer complete
 100
 101     *** exit status: 0 ***
 102     ## Total Size      = 0x0025d052 = 2478162 Bytes
 103     ## Switch baudrate to 115200 bps and press ESC ...
 104
 105     *** baud: 115200
 106
 107     *** baud: 115200 ***
 108     =>
 109
 110 Running Programs
 111 ^^^^^^^^^^^^^^^^
 112
 113 Binaries
 114 """"""""
 115
 116 To run a bare binary, use the ``go`` command:
 117
 118 .. code-block:: none
 119
 120     => loady
 121     ## Ready for binary (ymodem) download to 0x80000000 at 115200 bps...
 122     C
 123     *** file: ./examples/standalone/hello_world.bin
 124     $ sz -vv ./examples/standalone/hello_world.bin
 125     Sending: hello_world.bin
 126     Bytes Sent:   4864   BPS:649
 127     Sending:
 128     Ymodem sectors/kbytes sent:   0/ 0k
 129     Transfer complete
 130
 131     *** exit status: 0 ***
 132     (CAN) packets, 5 retries
 133     ## Total Size      = 0x000012f8 = 4856 Bytes
 134     => go 80000000
 135     ## Starting application at 0x80000000 ...
 136     Example expects ABI version 9
 137     Actual U-Boot ABI version 9
 138     Hello World
 139     argc = 1
 140     argv[0] = "80000000"
 141     argv[1] = "<NULL>"
 142     Hit any key to exit ...
 143
 144 Legacy Images
 145 """""""""""""
 146
 147 To run legacy images, use the ``bootm`` command:
 148
 149 .. code-block:: none
 150
 151     $ tools/mkimage -A riscv -O u-boot -T standalone -C none -a 80000000 -e 80000000 -d examples/standalone/hello_world.bin hello_world.img
 152     Image Name:
 153     Created:      Thu Mar  5 12:04:10 2020
 154     Image Type:   RISC-V U-Boot Standalone Program (uncompressed)
 155     Data Size:    4856 Bytes = 4.74 KiB = 0.00 MiB
 156     Load Address: 80000000
 157     Entry Point:  80000000
 158
 159     $ picocom -b 115200 /dev/ttyUSB0i
 160     => loady
 161     ## Ready for binary (ymodem) download to 0x80000000 at 115200 bps...
 162     C
 163     *** file: hello_world.img
 164     $ sz -vv hello_world.img
 165     Sending: hello_world.img
 166     Bytes Sent:   4992   BPS:665
 167     Sending:
 168     Ymodem sectors/kbytes sent:   0/ 0k
 169     Transfer complete
 170
 171     *** exit status: 0 ***
 172     CAN) packets, 3 retries
 173     ## Total Size      = 0x00001338 = 4920 Bytes
 174     => bootm
 175     ## Booting kernel from Legacy Image at 80000000 ...
 176        Image Name:
 177        Image Type:   RISC-V U-Boot Standalone Program (uncompressed)
 178        Data Size:    4856 Bytes = 4.7 KiB
 179        Load Address: 80000000
 180        Entry Point:  80000000
 181        Verifying Checksum ... OK
 182        Loading Standalone Program
 183     Example expects ABI version 9
 184     Actual U-Boot ABI version 9
 185     Hello World
 186     argc = 0
 187     argv[0] = "<NULL>"
 188     Hit any key to exit ...
 189
 190 Over- and Under-clocking
 191 ------------------------
 192
 193 To change the clock speed of the K210, you will need to enable
 194 ``CONFIG_CLK_K210_SET_RATE`` and edit the board's device tree. To do this, add a
 195 section to ``arch/riscv/arch/riscv/dts/k210-maix-bit.dts`` like the following:
 196
 197 .. code-block:: none
 198
 199     &sysclk {
 200         assigned-clocks = <&sysclk K210_CLK_PLL0>;
 201         assigned-clock-rates = <800000000>;
 202     };
 203
 204 There are three PLLs on the K210: PLL0 is the parent of most of the components,
 205 including the CPU and RAM. PLL1 is the parent of the neural network coprocessor.
 206 PLL2 is the parent of the sound processing devices. Note that child clocks of
 207 PLL0 and PLL2 run at *half* the speed of the PLLs. For example, if PLL0 is
 208 running at 800 MHz, then the CPU will run at 400 MHz. This is the example given
 209 above. The CPU can be overclocked to around 600 MHz, and underclocked to 26 MHz.
 210
 211 It is possible to set PLL2's parent to PLL0. The plls are more accurate when
 212 converting between similar frequencies. This makes it easier to get an accurate
 213 frequency for I2S. As an example, consider sampling an I2S device at 44.1 kHz.
 214 On this device, the I2S serial clock runs at 64 times the sample rate.
 215 Therefore, we would like to run PLL2 at an even multiple of 2.8224 MHz. If
 216 PLL2's parent is IN0, we could use a frequency of 390 MHz (the same as the CPU's
 217 default speed).  Dividing by 138 yields a serial clock of about 2.8261 MHz. This
 218 results in a sample rate of 44.158 kHz---around 50 Hz or .1% too fast. If,
 219 instead, we set PLL2's parent to PLL1 running at 390 MHz, and request a rate of
 220 2.8224 * 136 = 383.8464 MHz, the achieved rate is 383.90625 MHz. Dividing by 136
 221 yields a serial clock of about 2.8228 MHz. This results in a sample rate of
 222 44.107 kHz---just 7 Hz or .02% too fast. This configuration is shown in the
 223 following example:
 224
 225 .. code-block:: none
 226
 227     &sysclk {
 228         assigned-clocks = <&sysclk K210_CLK_PLL1>, <&sysclk K210_CLK_PLL2>;
 229         assigned-clock-parents = <0>, <&sysclk K210_CLK_PLL1>;
 230         assigned-clock-rates = <390000000>, <383846400>;
 231     };
 232
 233 There are a couple of quirks to the PLLs. First, there are more frequency ratios
 234 just above and below 1.0, but there is a small gap around 1.0. To be explicit,
 235 if the input frequency is 100 MHz, it would be impossible to have an output of
 236 99 or 101 MHz. In addition, there is a maximum frequency for the internal VCO,
 237 so higher input/output frequencies will be less accurate than lower ones.
 238
 239 Technical Details
 240 -----------------
 241
 242 Boot Sequence
 243 ^^^^^^^^^^^^^
 244
 245 1. ``RESET`` pin is deasserted.
 246 2. Both harts begin executing at ``0x00001000``.
 247 3. Both harts jump to firmware at ``0x88000000``.
 248 4. One hart is chosen as a boot hart.
 249 5. Firmware reads value of pin ``IO_16`` (ISP).
 250
 251    * If the pin is low, enter ISP mode. This mode allows loading data to ram,
 252      writing it to flash, and booting from specific addresses.
 253    * If the pin is high, continue boot.
 254 6. Firmware reads the next stage from flash (SPI3) to address ``0x80000000``.
 255
 256    * If byte 0 is 1, the next stage is decrypted using the built-in AES
 257      accelerator and the one-time programmable, 128-bit AES key.
 258    * Bytes 1 to 4 hold the length of the next stage.
 259    * The SHA-256 sum of the next stage is automatically calculated, and verified
 260      against the 32 bytes following the next stage.
 261 7. The boot hart sends an IPI to the other hart telling it to jump to the next
 262    stage.
 263 8. The boot hart jumps to ``0x80000000``.
 264
 265 Debug UART
 266 ^^^^^^^^^^
 267
 268 The Debug UART is provided with the following settings::
 269
 270     CONFIG_DEBUG_UART=y
 271     CONFIG_DEBUG_UART_SIFIVE=y
 272     CONFIG_DEBUG_UART_BASE=0x38000000
 273     CONFIG_DEBUG_UART_CLOCK=390000000
 274
 275 Resetting the board
 276 ^^^^^^^^^^^^^^^^^^^
 277
 278 The MAIX boards can be reset using the DTR and RTS lines of the serial console.
 279 How the lines are used depends on the specific board. See the code of kflash.py
 280 for details.
 281
 282 This is the reset sequence for the MAXDUINO and MAIX BiT with Mic:
 283
 284 .. code-block:: python
 285
 286    def reset(self):
 287         self.device.setDTR(False)
 288         self.device.setRTS(False)
 289         time.sleep(0.1)
 290         self.device.setDTR(True)
 291         time.sleep(0.1)
 292         self.device.setDTR(False)
 293         time.sleep(0.1)
 294
 295 and this for the MAIX Bit:
 296
 297 .. code-block:: python
 298
 299    def reset(self):
 300         self.device.setDTR(False)
 301         self.device.setRTS(False)
 302         time.sleep(0.1)
 303         self.device.setRTS(True)
 304         time.sleep(0.1)
 305         self.device.setRTS(False)
 306         time.sleep(0.1)
 307
 308 Memory Map
 309 ^^^^^^^^^^
 310
 311 ========== ========= ===========
 312 Address    Size      Description
 313 ========== ========= ===========
 314 0x00000000 0x1000    debug
 315 0x00001000 0x1000    rom
 316 0x02000000 0xC000    clint
 317 0x0C000000 0x4000000 plic
 318 0x38000000 0x1000    uarths
 319 0x38001000 0x1000    gpiohs
 320 0x40000000 0x400000  sram0 (non-cached)
 321 0x40400000 0x200000  sram1 (non-cached)
 322 0x40600000 0x200000  airam (non-cached)
 323 0x40800000 0xC00000  kpu
 324 0x42000000 0x400000  fft
 325 0x50000000 0x1000    dmac
 326 0x50200000 0x200000  apb0
 327 0x50200000 0x80      gpio
 328 0x50210000 0x100     uart0
 329 0x50220000 0x100     uart1
 330 0x50230000 0x100     uart2
 331 0x50240000 0x100     spi slave
 332 0x50250000 0x200     i2s0
 333 0x50250200 0x200     apu
 334 0x50260000 0x200     i2s1
 335 0x50270000 0x200     i2s2
 336 0x50280000 0x100     i2c0
 337 0x50290000 0x100     i2c1
 338 0x502A0000 0x100     i2c2
 339 0x502B0000 0x100     fpioa
 340 0x502C0000 0x100     sha256
 341 0x502D0000 0x100     timer0
 342 0x502E0000 0x100     timer1
 343 0x502F0000 0x100     timer2
 344 0x50400000 0x200000  apb1
 345 0x50400000 0x100     wdt0
 346 0x50410000 0x100     wdt1
 347 0x50420000 0x100     otp control
 348 0x50430000 0x100     dvp
 349 0x50440000 0x100     sysctl
 350 0x50450000 0x100     aes
 351 0x50460000 0x100     rtc
 352 0x52000000 0x4000000 apb2
 353 0x52000000 0x100     spi0
 354 0x53000000 0x100     spi1
 355 0x54000000 0x200     spi3
 356 0x80000000 0x400000  sram0 (cached)
 357 0x80400000 0x200000  sram1 (cached)
 358 0x80600000 0x200000  airam (cached)
 359 0x88000000 0x20000   otp
 360 0x88000000 0xC200    firmware
 361 0x8801C000 0x1000    riscv priv spec 1.9 config
 362 0x8801D000 0x2000    flattened device tree (contains only addresses and
 363                      interrupts)
 364 0x8801f000 0x1000    credits
 365 ========== ========= ===========