1.. zephyr:board:: tlsr9518adk80d 2 3Overview 4******** 5 6The TLSR9518A Generic Starter Kit is a hardware platform which 7can be used to verify the `Telink TLSR951x series chipset`_ and develop applications 8for several 2.4 GHz air interface standards including Bluetooth 5.2 (Basic data 9rate, Enhanced data rate, LE, Indoor positioning and BLE Mesh), 10Zigbee 3.0, Homekit, 6LoWPAN, Thread and 2.4 Ghz proprietary. 11 12More information about the board can be found at the `Telink B91 Generic Starter Kit Hardware Guide`_ website. 13 14Hardware 15******** 16 17The TLSR9518A SoC integrates a powerful 32-bit RISC-V MCU, DSP, AI Engine, 2.4 GHz ISM Radio, 256 18KB SRAM (128 KB of Data Local Memory and 128 KB of Instruction Local Memory), external Flash memory, 19stereo audio codec, 14 bit AUX ADC, analog and digital Microphone input, PWM, flexible IO interfaces, 20and other peripheral blocks required for advanced IoT, hearable, and wearable devices. 21 22.. figure:: img/tlsr9518_block_diagram.jpg 23 :align: center 24 :alt: TLSR9518ADK80D_SOC 25 26The TLSR9518ADK80D default board configuration provides the following hardware components: 27 28- RF conducted antenna 29- 1 MB External Flash memory with reset button 30- Chip reset button 31- Mini USB interface 32- 4-wire JTAG 33- 4 LEDs, Key matrix up to 4 keys 34- 2 line-in function (Dual Analog microphone supported when switching jumper from microphone path) 35- Dual Digital microphone 36- Stereo line-out 37 38Supported Features 39================== 40 41The Zephyr TLSR9518ADK80D board configuration supports the following hardware features: 42 43+----------------+------------+------------------------------+ 44| Interface | Controller | Driver/Component | 45+================+============+==============================+ 46| PLIC | on-chip | interrupt_controller | 47+----------------+------------+------------------------------+ 48| RISC-V Machine | on-chip | timer | 49| Timer (32 KHz) | | | 50+----------------+------------+------------------------------+ 51| PINCTRL | on-chip | pinctrl | 52+----------------+------------+------------------------------+ 53| GPIO | on-chip | gpio | 54+----------------+------------+------------------------------+ 55| UART | on-chip | serial | 56+----------------+------------+------------------------------+ 57| PWM | on-chip | pwm | 58+----------------+------------+------------------------------+ 59| TRNG | on-chip | entropy | 60+----------------+------------+------------------------------+ 61| FLASH (MSPI) | on-chip | flash | 62+----------------+------------+------------------------------+ 63| RADIO | on-chip | Bluetooth, | 64| | | ieee802154, OpenThread | 65+----------------+------------+------------------------------+ 66| SPI (Master) | on-chip | spi | 67+----------------+------------+------------------------------+ 68| I2C (Master) | on-chip | i2c | 69+----------------+------------+------------------------------+ 70| ADC | on-chip | adc | 71+----------------+------------+------------------------------+ 72 73.. note:: 74 To support "button" example project PC3-KEY3 (J20-19, J20-20) jumper needs to be removed and KEY3 (J20-19) should be connected to VDD3_DCDC (J51-13) externally. 75 76 For the rest example projects use the default jumpers configuration. 77 78Other hardware features and example projects are not supported yet. 79 80Limitations 81----------- 82 83- Maximum 3 GPIO pins could be configured to generate interrupts simultaneously. All pins must be related to different ports and use different IRQ numbers. 84- DMA mode is not supported by I2C, SPI and Serial Port. 85- UART hardware flow control is not implemented. 86- SPI Slave mode is not implemented. 87- I2C Slave mode is not implemented. 88 89Default configuration and IOs 90============================= 91 92System Clock 93------------ 94 95The TLSR9518ADK80D board is configured to use the 24 MHz external crystal oscillator 96with the on-chip PLL/DIV generating the 48 MHz system clock. 97The following values also could be assigned to the system clock in the board DTS file 98:zephyr_file:`boards/telink/tlsr9518adk80d/tlsr9518adk80d.dts`: 99 100- 16000000 101- 24000000 102- 32000000 103- 48000000 104- 64000000 105- 96000000 106 107.. code-block:: 108 109 &cpu0 { 110 clock-frequency = <48000000>; 111 }; 112 113PINs Configuration 114------------------ 115 116The TLSR9518A SoC has five GPIO controllers (PORT_A to PORT_E), but only two are 117currently enabled (PORT_B for LEDs control and PORT_C for buttons) in the board DTS file: 118 119- LED0 (blue): PB4, LED1 (green): PB5, LED2 (white): PB6, LED3 (red): PB7 120- Key Matrix SW0: PC2_PC3, SW1: PC2_PC1, SW2: PC0_PC3, SW3: PC0_PC1 121 122Peripheral's pins on the SoC are mapped to the following GPIO pins in the 123:zephyr_file:`boards/telink/tlsr9518adk80d/tlsr9518adk80d.dts` file: 124 125- UART0 TX: PB2, RX: PB3 126- UART1 TX: PC6, RX: PC7 127- PWM Channel 0: PB4 128- PSPI CS0: PC4, CLK: PC5, MISO: PC6, MOSI: PC7 129- HSPI CS0: PA1, CLK: PA2, MISO: PA3, MOSI: PA4 130- I2C SCL: PE1, SDA: PE3 131 132Serial Port 133----------- 134 135The TLSR9518A SoC has 2 UARTs. The Zephyr console output is assigned to UART0. 136The default settings are 115200 8N1. 137 138Programming and debugging 139************************* 140 141Building 142======== 143 144.. important:: 145 146 These instructions assume you've set up a development environment as 147 described in the :ref:`getting_started`. 148 149To build applications using the default RISC-V toolchain from Zephyr SDK, just run the west build command. 150Here is an example for the "hello_world" application. 151 152.. code-block:: console 153 154 # From the root of the zephyr repository 155 west build -b tlsr9518adk80d samples/hello_world 156 157To use `Telink RISC-V Linux Toolchain`_, ``ZEPHYR_TOOLCHAIN_VARIANT`` and ``CROSS_COMPILE`` variables need to be set. 158In addition ``CONFIG_FPU=y`` must be selected in :zephyr_file:`boards/telink/tlsr9518adk80d/tlsr9518adk80d_defconfig` file since this 159toolchain is compatible only with the float point unit usage. 160 161.. code-block:: console 162 163 # Set Zephyr toolchain variant to cross-compile 164 export ZEPHYR_TOOLCHAIN_VARIANT=cross-compile 165 # Specify the Telink RISC-V Toolchain location 166 export CROSS_COMPILE=~/toolchains/nds32le-elf-mculib-v5f/bin/riscv32-elf- 167 # From the root of the zephyr repository 168 west build -b tlsr9518adk80d samples/hello_world 169 170`Telink RISC-V Linux Toolchain`_ is available on the `Burning and Debugging Tools for TLSR9 Series in Linux`_ page. 171 172Open a serial terminal with the following settings: 173 174- Speed: 115200 175- Data: 8 bits 176- Parity: None 177- Stop bits: 1 178 179Flash the board, reset and observe the following messages on the selected 180serial port: 181 182.. code-block:: console 183 184 *** Booting Zephyr OS version 2.5.0 *** 185 Hello World! tlsr9518adk80d 186 187 188Flashing 189======== 190 191To flash the TLSR9518ADK80D board see the sources below: 192 193- `Burning and Debugging Tools for all Series`_ 194- `Burning and Debugging Tools for TLSR9 Series`_ 195- `Burning and Debugging Tools for TLSR9 Series in Linux`_ 196 197It is also possible to use the west flash command, but additional steps are required to set it up: 198 199- Download `Telink RISC-V Linux Toolchain`_. The toolchain contains tools for the board flashing as well. 200- Since the ICEman tool is created for the 32-bit OS version it is necessary to install additional packages in case of the 64-bit OS version. 201 202.. code-block:: console 203 204 sudo dpkg --add-architecture i386 205 sudo apt-get update 206 sudo apt-get install -y libc6:i386 libncurses5:i386 libstdc++6:i386 207 208- Run the "ICEman.sh" script. 209 210.. code-block:: console 211 212 # From the root of the {path to the Telink RISC-V Linux Toolchain}/ice repository 213 sudo ./ICEman.sh 214 215- Now you should be able to run the west flash command with the toolchain path specified (TELINK_TOOLCHAIN_PATH). 216 217.. code-block:: console 218 219 west flash --telink-tools-path=$TELINK_TOOLCHAIN_PATH 220 221- You can also run the west flash command without toolchain path specification if add SPI_burn and ICEman to PATH. 222 223.. code-block:: console 224 225 export PATH=$TELINK_TOOLCHAIN_PATH/flash/bin:"$PATH" 226 export PATH=$TELINK_TOOLCHAIN_PATH/ice:"$PATH" 227 228Debugging 229========= 230 231This port supports UART debug and OpenOCD+GDB. The ``west debug`` command also supported. You may run 232it in a simple way, like: 233 234.. code-block:: console 235 236 west debug 237 238Or with additional arguments, like: 239 240.. code-block:: console 241 242 west debug --gdb-port=<port_number> --gdb-ex=<additional_ex_arguments> 243 244Example: 245 246.. code-block:: console 247 248 west debug --gdb-port=1111 --gdb-ex="-ex monitor reset halt -ex b main -ex continue" 249 250References 251********** 252 253.. target-notes:: 254 255.. _Telink TLSR951x series chipset: https://wiki.telink-semi.cn/wiki/chip-series/TLSR951x-Series/ 256.. _Telink B91 Generic Starter Kit Hardware Guide: https://wiki.telink-semi.cn/wiki/Hardware/B91_Generic_Starter_Kit_Hardware_Guide/ 257.. _Telink RISC-V Linux Toolchain: https://wiki.telink-semi.cn/tools_and_sdk/Tools/IDE/telink_riscv_linux_toolchain.zip 258.. _Burning and Debugging Tools for all Series: https://wiki.telink-semi.cn/wiki/IDE-and-Tools/Burning-and-Debugging-Tools-for-all-Series/ 259.. _Burning and Debugging Tools for TLSR9 Series: https://wiki.telink-semi.cn/wiki/IDE-and-Tools/Burning-and-Debugging-Tools-for-TLSR9-Series/ 260.. _Burning and Debugging Tools for TLSR9 Series in Linux: https://wiki.telink-semi.cn/wiki/IDE-and-Tools/BDT_for_TLSR9_Series_in_Linux/ 261
