summaryrefslogtreecommitdiff
path: root/doc/board
diff options
context:
space:
mode:
Diffstat (limited to 'doc/board')
-rw-r--r--doc/board/index.rst2
-rw-r--r--doc/board/sipeed/index.rst9
-rw-r--r--doc/board/sipeed/maix.rst298
-rw-r--r--doc/board/tbs/index.rst9
-rw-r--r--doc/board/tbs/tbs2910.rst191
-rw-r--r--doc/board/xilinx/zynq.rst19
6 files changed, 528 insertions, 0 deletions
diff --git a/doc/board/index.rst b/doc/board/index.rst
index dc683f0acb..0a15899180 100644
--- a/doc/board/index.rst
+++ b/doc/board/index.rst
@@ -18,6 +18,8 @@ Board-specific doc
renesas/index
rockchip/index
sifive/index
+ sipeed/index
st/index
+ tbs/index
toradex/index
xilinx/index
diff --git a/doc/board/sipeed/index.rst b/doc/board/sipeed/index.rst
new file mode 100644
index 0000000000..3518e2d8f4
--- /dev/null
+++ b/doc/board/sipeed/index.rst
@@ -0,0 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Sipeed
+======
+
+.. toctree::
+ :maxdepth: 2
+
+ maix
diff --git a/doc/board/sipeed/maix.rst b/doc/board/sipeed/maix.rst
new file mode 100644
index 0000000000..06e0008b9f
--- /dev/null
+++ b/doc/board/sipeed/maix.rst
@@ -0,0 +1,298 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright (C) 2020 Sean Anderson <seanga2@gmail.com>
+
+Maix Bit
+========
+
+Several of the Sipeed Maix series of boards cotain the Kendryte K210 processor,
+a 64-bit RISC-V CPU. This processor contains several peripherals to accelerate
+neural network processing and other "ai" tasks. This includes a "KPU" neural
+network processor, an audio processor supporting beamforming reception, and a
+digital video port supporting capture and output at VGA resolution. Other
+peripherals include 8M of SRAM (accessible with and without caching); remappable
+pins, including 40 GPIOs; AES, FFT, and SHA256 accelerators; a DMA controller;
+and I2C, I2S, and SPI controllers. Maix peripherals vary, but include spi flash;
+on-board usb-serial bridges; ports for cameras, displays, and sd cards; and
+ESP32 chips. Currently, only the Sipeed Maix Bit V2.0 (bitm) is supported, but
+the boards are fairly similar.
+
+Documentation for Maix boards is available from
+`Sipeed's website <http://dl.sipeed.com/MAIX/HDK/>`_.
+Documentation for the Kendryte K210 is available from
+`Kendryte's website <https://kendryte.com/downloads/>`_. However, hardware
+details are rather lacking, so most technical reference has been taken from the
+`standalone sdk <https://github.com/kendryte/kendryte-standalone-sdk>`_.
+
+Build and boot steps
+--------------------
+
+To build u-boot, run
+
+.. code-block:: none
+
+ make sipeed_maix_bitm_defconfig
+ make CROSS_COMPILE=<your cross compile prefix>
+
+To flash u-boot to a maix bit, run
+
+.. code-block:: none
+
+ kflash -tp /dev/<your tty here> -B bit_mic u-boot-dtb.bin
+
+Boot output should look like the following:
+
+.. code-block:: none
+
+ U-Boot 2020.04-rc2-00087-g2221cc09c1-dirty (Feb 28 2020 - 13:53:09 -0500)
+
+ DRAM: 8 MiB
+ In: serial@38000000
+ Out: serial@38000000
+ Err: serial@38000000
+ =>
+
+Loading Images
+^^^^^^^^^^^^^^
+
+To load a kernel, transfer it over serial.
+
+.. code-block:: none
+
+ => loady 80000000 1500000
+ ## Switch baudrate to 1500000 bps and press ENTER ...
+
+ *** baud: 1500000
+
+ *** baud: 1500000 ***
+ ## Ready for binary (ymodem) download to 0x80000000 at 1500000 bps...
+ C
+ *** file: loader.bin
+ $ sz -vv loader.bin
+ Sending: loader.bin
+ Bytes Sent:2478208 BPS:72937
+ Sending:
+ Ymodem sectors/kbytes sent: 0/ 0k
+ Transfer complete
+
+ *** exit status: 0 ***
+ ## Total Size = 0x0025d052 = 2478162 Bytes
+ ## Switch baudrate to 115200 bps and press ESC ...
+
+ *** baud: 115200
+
+ *** baud: 115200 ***
+ =>
+
+Running Programs
+^^^^^^^^^^^^^^^^
+
+Binaries
+""""""""
+
+To run a bare binary, use the ``go`` command:
+
+.. code-block:: none
+
+ => loady
+ ## Ready for binary (ymodem) download to 0x80000000 at 115200 bps...
+ C
+ *** file: ./examples/standalone/hello_world.bin
+ $ sz -vv ./examples/standalone/hello_world.bin
+ Sending: hello_world.bin
+ Bytes Sent: 4864 BPS:649
+ Sending:
+ Ymodem sectors/kbytes sent: 0/ 0k
+ Transfer complete
+
+ *** exit status: 0 ***
+ (CAN) packets, 5 retries
+ ## Total Size = 0x000012f8 = 4856 Bytes
+ => go 80000000
+ ## Starting application at 0x80000000 ...
+ Example expects ABI version 9
+ Actual U-Boot ABI version 9
+ Hello World
+ argc = 1
+ argv[0] = "80000000"
+ argv[1] = "<NULL>"
+ Hit any key to exit ...
+
+Legacy Images
+"""""""""""""
+
+To run legacy images, use the ``bootm`` command:
+
+.. code-block:: none
+
+ $ tools/mkimage -A riscv -O u-boot -T standalone -C none -a 80000000 -e 80000000 -d examples/standalone/hello_world.bin hello_world.img
+ Image Name:
+ Created: Thu Mar 5 12:04:10 2020
+ Image Type: RISC-V U-Boot Standalone Program (uncompressed)
+ Data Size: 4856 Bytes = 4.74 KiB = 0.00 MiB
+ Load Address: 80000000
+ Entry Point: 80000000
+
+ $ picocom -b 115200 /dev/ttyUSB0i
+ => loady
+ ## Ready for binary (ymodem) download to 0x80000000 at 115200 bps...
+ C
+ *** file: hello_world.img
+ $ sz -vv hello_world.img
+ Sending: hello_world.img
+ Bytes Sent: 4992 BPS:665
+ Sending:
+ Ymodem sectors/kbytes sent: 0/ 0k
+ Transfer complete
+
+ *** exit status: 0 ***
+ CAN) packets, 3 retries
+ ## Total Size = 0x00001338 = 4920 Bytes
+ => bootm
+ ## Booting kernel from Legacy Image at 80000000 ...
+ Image Name:
+ Image Type: RISC-V U-Boot Standalone Program (uncompressed)
+ Data Size: 4856 Bytes = 4.7 KiB
+ Load Address: 80000000
+ Entry Point: 80000000
+ Verifying Checksum ... OK
+ Loading Standalone Program
+ Example expects ABI version 9
+ Actual U-Boot ABI version 9
+ Hello World
+ argc = 0
+ argv[0] = "<NULL>"
+ Hit any key to exit ...
+
+Over- and Under-clocking
+------------------------
+
+To change the clock speed of the K210, you will need to enable
+``CONFIG_CLK_K210_SET_RATE`` and edit the board's device tree. To do this, add a
+section to ``arch/riscv/arch/riscv/dts/k210-maix-bit.dts`` like the following:
+
+.. code-block:: none
+
+ &sysclk {
+ assigned-clocks = <&sysclk K210_CLK_PLL0>;
+ assigned-clock-rates = <800000000>;
+ };
+
+There are three PLLs on the K210: PLL0 is the parent of most of the components,
+including the CPU and RAM. PLL1 is the parent of the neural network coprocessor.
+PLL2 is the parent of the sound processing devices. Note that child clocks of
+PLL0 and PLL2 run at *half* the speed of the PLLs. For example, if PLL0 is
+running at 800 MHz, then the CPU will run at 400 MHz. This is the example given
+above. The CPU can be overclocked to around 600 MHz, and underclocked to 26 MHz.
+
+It is possible to set PLL2's parent to PLL0. The plls are more accurate when
+converting between similar frequencies. This makes it easier to get an accurate
+frequency for I2S. As an example, consider sampling an I2S device at 44.1 kHz.
+On this device, the I2S serial clock runs at 64 times the sample rate.
+Therefore, we would like to run PLL2 at an even multiple of 2.8224 MHz. If
+PLL2's parent is IN0, we could use a frequency of 390 MHz (the same as the CPU's
+default speed). Dividing by 138 yields a serial clock of about 2.8261 MHz. This
+results in a sample rate of 44.158 kHz---around 50 Hz or .1% too fast. If,
+instead, we set PLL2's parent to PLL1 running at 390 MHz, and request a rate of
+2.8224 * 136 = 383.8464 MHz, the achieved rate is 383.90625 MHz. Dividing by 136
+yields a serial clock of about 2.8228 MHz. This results in a sample rate of
+44.107 kHz---just 7 Hz or .02% too fast. This configuration is shown in the
+following example:
+
+.. code-block:: none
+
+ &sysclk {
+ assigned-clocks = <&sysclk K210_CLK_PLL1>, <&sysclk K210_CLK_PLL2>;
+ assigned-clock-parents = <0>, <&sysclk K210_CLK_PLL1>;
+ assigned-clock-rates = <390000000>, <383846400>;
+ };
+
+There are a couple of quirks to the PLLs. First, there are more frequency ratios
+just above and below 1.0, but there is a small gap around 1.0. To be explicit,
+if the input frequency is 100 MHz, it would be impossible to have an output of
+99 or 101 MHz. In addition, there is a maximum frequency for the internal VCO,
+so higher input/output frequencies will be less accurate than lower ones.
+
+Technical Details
+-----------------
+
+Boot Sequence
+^^^^^^^^^^^^^
+
+1. ``RESET`` pin is deasserted.
+2. Both harts begin executing at ``0x00001000``.
+3. Both harts jump to firmware at ``0x88000000``.
+4. One hart is chosen as a boot hart.
+5. Firmware reads value of pin ``IO_16`` (ISP).
+
+ * If the pin is low, enter ISP mode. This mode allows loading data to ram,
+ writing it to flash, and booting from specific addresses.
+ * If the pin is high, continue boot.
+6. Firmware reads the next stage from flash (SPI3) to address ``0x80000000``.
+
+ * If byte 0 is 1, the next stage is decrypted using the built-in AES
+ accelerator and the one-time programmable, 128-bit AES key.
+ * Bytes 1 to 4 hold the length of the next stage.
+ * The SHA-256 sum of the next stage is automatically calculated, and verified
+ against the 32 bytes following the next stage.
+7. The boot hart sends an IPI to the other hart telling it to jump to the next
+ stage.
+8. The boot hart jumps to ``0x80000000``.
+
+Memory Map
+^^^^^^^^^^
+
+========== ========= ===========
+Address Size Description
+========== ========= ===========
+0x00000000 0x1000 debug
+0x00001000 0x1000 rom
+0x02000000 0xC000 clint
+0x0C000000 0x4000000 plic
+0x38000000 0x1000 uarths
+0x38001000 0x1000 gpiohs
+0x40000000 0x400000 sram0 (non-cached)
+0x40400000 0x200000 sram1 (non-cached)
+0x40600000 0x200000 airam (non-cached)
+0x40800000 0xC00000 kpu
+0x42000000 0x400000 fft
+0x50000000 0x1000 dmac
+0x50200000 0x200000 apb0
+0x50200000 0x80 gpio
+0x50210000 0x100 uart0
+0x50220000 0x100 uart1
+0x50230000 0x100 uart2
+0x50240000 0x100 spi slave
+0x50250000 0x200 i2s0
+0x50250200 0x200 apu
+0x50260000 0x200 i2s1
+0x50270000 0x200 i2s2
+0x50280000 0x100 i2c0
+0x50290000 0x100 i2c1
+0x502A0000 0x100 i2c2
+0x502B0000 0x100 fpioa
+0x502C0000 0x100 sha256
+0x502D0000 0x100 timer0
+0x502E0000 0x100 timer1
+0x502F0000 0x100 timer2
+0x50400000 0x200000 apb1
+0x50400000 0x100 wdt0
+0x50410000 0x100 wdt1
+0x50420000 0x100 otp control
+0x50430000 0x100 dvp
+0x50440000 0x100 sysctl
+0x50450000 0x100 aes
+0x50460000 0x100 rtc
+0x52000000 0x4000000 apb2
+0x52000000 0x100 spi0
+0x53000000 0x100 spi1
+0x54000000 0x200 spi3
+0x80000000 0x400000 sram0 (cached)
+0x80400000 0x200000 sram1 (cached)
+0x80600000 0x200000 airam (cached)
+0x88000000 0x20000 otp
+0x88000000 0xC200 firmware
+0x8801C000 0x1000 riscv priv spec 1.9 config
+0x8801D000 0x2000 flattened device tree (contains only addresses and
+ interrupts)
+0x8801f000 0x1000 credits
+========== ========= ===========
diff --git a/doc/board/tbs/index.rst b/doc/board/tbs/index.rst
new file mode 100644
index 0000000000..b677bc624f
--- /dev/null
+++ b/doc/board/tbs/index.rst
@@ -0,0 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+TBS
+===
+
+.. toctree::
+ :maxdepth: 2
+
+ tbs2910
diff --git a/doc/board/tbs/tbs2910.rst b/doc/board/tbs/tbs2910.rst
new file mode 100644
index 0000000000..e97f2b6e61
--- /dev/null
+++ b/doc/board/tbs/tbs2910.rst
@@ -0,0 +1,191 @@
+TBS2910 Matrix ARM miniPC
+=========================
+
+Building
+--------
+To build u-boot for the TBS2910 Matrix ARM miniPC, you can use the following
+procedure:
+
+First add the ARM toolchain to your PATH
+
+Then setup the ARCH and cross compilation environment variables.
+
+When this is done you can then build u-boot for the TBS2910 Matrix ARM miniPC
+with the following commands:
+
+.. code-block:: none
+
+ make mrproper
+ make tbs2910_defconfig
+ make
+
+Once the build is complete, you can find the resulting image as u-boot.imx in
+the current directory.
+
+UART
+----
+The UART voltage is at 3.3V and its settings are 115200bps 8N1
+
+BOOT/UPDATE boot switch:
+------------------------
+The BOOT/UPDATE switch (SW11) is connected to the BOOT_MODE0 and
+BOOT_MODE1 SoC pins. It has "BOOT" and "UPDATE" markings both on
+the PCB and on the plastic case.
+
+When set to the "UPDATE" position, the SoC will use the "Boot From Fuses"
+configuration, and since BT_FUSE_SEL is 0, this makes the SOC jump to serial
+downloader.
+
+When set in the "BOOT" position, the SoC will use the "Internal boot"
+configuration, and since BT_FUSE_SEL is 0, it will then use the GPIO pins
+for the boot configuration.
+
+SW6 binary DIP switch array on the PCB revision 2.1:
+----------------------------------------------------
+On that PCB revision, SW6 has 8 positions.
+
+Switching a position to ON sets the corresponding
+register to 1.
+
+See the following table for a correspondence between the switch positions and
+registers:
+
+=============== ============
+Switch position Register
+=============== ============
+1 BOOT_CFG2[3]
+2 BOOT_CFG2[4]
+3 BOOT_CFG2[5]
+4 BOOT_CFG2[6]
+5 BOOT_CFG1[4]
+6 BOOT_CFG1[5]
+7 BOOT_CFG1[6]
+8 BOOT_CFG1[7]
+=============== ============
+
+For example:
+
+ - To boot from the eMMC: 1:ON , 2:ON, 3:ON, 4:OFF, 5:OFF, 6:ON, 7:ON, 8:OFF
+ - To boot from the microSD slot: 1: ON, 2: OFF, 3: OFF, 4: OFF, 5:OFF, 6:OFF,
+ 7:ON, 8:OFF
+ - To boot from the SD slot: 1: OFF, 2: ON, 3: OFF, 4: OFF, 5:OFF, 6:OFF, 7:ON,
+ 8:OFF
+ - To boot from SATA: 1: OFF, 2: OFF, 3: OFF, 4: OFF, 5:OFF, 6:ON, 7:OFF, 8:OFF
+
+You can refer to the BOOT_CFG registers in the I.MX6Q reference manual for
+additional details.
+
+SW6 binary DIP switch array on the PCB revision 2.3:
+----------------------------------------------------
+On that PCB revision, SW6 has only 4 positions.
+
+Switching a position to ON sets the corresponding
+register to 1.
+
+See the following table for a correspondence between the switch positions and
+registers:
+
+=============== ============
+Switch position Register
+=============== ============
+1 BOOT_CFG2[3]
+2 BOOT_CFG2[4]
+3 BOOT_CFG2[5]
+4 BOOT_CFG1[5]
+=============== ============
+
+For example:
+
+- To boot from the eMMC: 1:ON, 2:ON, 3:ON, 4:ON
+- To boot from the microSD slot: 1:ON, 2:OFF, 3:OFF, 4:OFF
+- To boot from the SD slot: 1:OFF, 2:ON, 3:OFF, 4:OFF
+
+You can refer to the BOOT_CFG registers in the I.MX6Q reference manual for
+additional details.
+
+Loading u-boot from USB:
+------------------------
+If you need to load u-boot from USB, you can use the following instructions:
+
+First build imx_usb_loader, as we will need it to load u-boot from USB. This
+can be done with the following commands:
+
+.. code-block:: none
+
+ git clone git://github.com/boundarydevices/imx_usb_loader.git
+ cd imx_usb_loader
+ make
+
+This will create the resulting imx_usb binary.
+
+When this is done, you can copy the u-boot.imx image that you built earlier
+in in the imx_usb_loader directory.
+
+You will then need to power off the TBS2910 Matrix ARM miniPC and make sure that
+the boot switch is set to "UPDATE"
+
+Once this is done you can connect an USB cable between the computer that will
+run imx_usb and the TBS2910 Matrix ARM miniPC.
+
+If you also need to access the u-boot console, you will also need to connect an
+UART cable between the computer running imx_usb and the TBS2910 Matrix ARM
+miniPC.
+
+Once everything is connected you can finally power on the TBS2910 Matrix ARM
+miniPC. The SoC will then jump to the serial download and wait for you.
+
+Finlay, you can load u-boot through USB with with the following command:
+
+.. code-block:: none
+
+ sudo ./imx_usb -v u-boot.imx
+
+The u-boot boot messages will then appear in the serial console.
+
+Install u-boot on the eMMC:
+---------------------------
+To install u-boot on the eMMC, you first need to boot the TBS2910 Matrix ARM
+miniPC.
+
+Once booted, you can flash u-boot.imx to mmcblk0boot0 with the
+following commands:
+
+.. code-block:: none
+
+ sudo echo 0 >/sys/block/mmcblk0boot0/force_ro
+ sudo dd if=u-boot.imx of=/dev/mmcblk0boot0 bs=1k seek=1; sync
+
+Note that the eMMC card node may vary, so adjust this as needed.
+
+Once the new u-boot version is installed, to boot on it you then need to power
+off the TBS2910 Matrix ARM miniPC.
+
+Once it is off, you need make sure that the boot switch is set to "BOOT" and
+that the SW6 switch is set to boot on the eMMC as described in the previous
+sections.
+
+If you also need to access the u-boot console, you will also need to connect an
+UART cable between the computer running imx_usb and the TBS2910 Matrix ARM
+miniPC.
+
+You can then power up the TBS2910 Matrix ARM miniPC and U-Boot messages will
+appear in the serial console.
+
+Booting a distribution:
+-----------------------
+When booting on the TBS2910 Matrix ARM miniPC, by default U-Boot will first try
+to boot from hardcoded offsets from the start of the eMMC. This is for
+compatibility with the stock GNU/Linux distribution.
+
+If that fails it will then try to boot from several interfaces using
+'distro_bootcmd': It will first try to boot from the microSD slot, then the
+SD slot, then the internal eMMC, then the SATA interface and finally the USB
+interface. For more information on how to configure your distribution to boot,
+see 'README.distro'.
+
+Links:
+------
+ - https://www.tbsdtv.com/download/document/tbs2910/TBS2910-Matrix-ARM-mini-PC-SCH_rev2.1.pdf
+ - The schematics for the revision 2.1 of the TBS2910 Matrix ARM miniPC.
+ - https://cache.freescale.com/files/32bit/doc/ref_manual/IMX6DQRM.pdf - The
+ SoC reference manual for additional details on the BOOT_CFG registers.
diff --git a/doc/board/xilinx/zynq.rst b/doc/board/xilinx/zynq.rst
index 6a09df1d15..f564434b69 100644
--- a/doc/board/xilinx/zynq.rst
+++ b/doc/board/xilinx/zynq.rst
@@ -60,6 +60,25 @@ SLCR bootmode register Bit[3:0] values
"modeboot" variable can assign any of "norboot", "sdboot" or "jtagboot"
bootmode strings at runtime.
+Flashing
+--------
+
+SD Card
+^^^^^^^
+
+To write an image that boots from a SD card first create a FAT32 partition
+and a FAT32 filesystem on the SD card::
+
+ sudo fdisk /dev/sdx
+ sudo mkfs.vfat -F 32 /dev/sdx1
+
+Mount the SD card and copy the SPL and U-Boot to the root directory of the
+SD card::
+
+ sudo mount -t vfat /dev/sdx1 /mnt
+ sudo cp spl/boot.bin /mnt
+ sudo cp u-boot.img /mnt
+
Mainline status
---------------
generated by cgit (git 2.34.1) at 2024-12-24 16:42:27 +0000