.. _sdk: How to develop with HBird SDK ============================= This chapter will introduce how to run Hello World demo on HBirdv2 E203 SoC with HBird SDK. HBird SDK introduction ###################### HBird SDK is a software platform built based on Makefile, which supports running in Windows/Linux system. As an intermediate platform that connect the upper-level application and underlying hardware, HBird SDK provides the application interface(API) required to operate the underlying hardware platform, so that users don't need to face cumbersome register configuration when developing applications, thereby improving development efficiency. The architecture of HBird SDK is shown in the figure below. .. _figure_sdk_0: .. figure:: /asserts/medias/sdk_fig0.png :width: 800 :alt: sdk_fig0 HBird SDK Architecture Setup tools and environment ########################### .. _quickstart_setup_tools_env_windows: Install and setup tools in Windows ---------------------------------- **1. Preparation** - Create a folder in your Windows Environment, which is used to store development tools. .. note:: Assuming that the directory is **, the abbreviation will be used in the following text. **2. Tools download** - Download the following tools from `Nuclei Download Center `__. .. _figure_sdk_1: .. figure:: /asserts/medias/sdk_fig1.png :width: 750 :alt: sdk_fig1 Nuclei tools need to be downloaded for Windows **3. Tools setup** Create *gcc*, *openocd*, *build-tools* folders under ** directory. - Extract the downloaded **gnu toolchain** into a temp folder, then copy the files into *gcc* folder, and make sure the structure of *gcc* directory looks the same as the figure below. .. _figure_sdk_2: .. figure:: /asserts/medias/sdk_fig2.png :width: 550 :alt: sdk_fig2 The structure of Nuclei RISC-V GCC Toolchain directory - Extract the downloaded **openocd** into a temp folder, then copy the files into *openocd* folder, and make sure the structure of *openocd* directory looks the same as the figure below. .. _figure_sdk_3: .. figure:: /asserts/medias/sdk_fig3.png :width: 550 :alt: sdk_fig3 The structure of Nuclei OpenOCD directory - Extract the downloaded **build-tools** into a temp folder, then copy the files into *build-tools* folder, and make sure the structure of *build-tools* directory looks the same as the figure below. .. _figure_sdk_4: .. figure:: /asserts/medias/sdk_fig4.png :width: 550 :alt: sdk_fig4 The structure of Nuclei Windows Build Tools directory Install and setup tools in Linux -------------------------------- **1. Preparation** - Create a folder in your Linux Environment, which is used to store development tools. .. note:: Assuming that the directory is **, the abbreviation will be used in the following text. **2. Tools download** - Download the following tools from `Nuclei Download Center `__. .. _figure_sdk_5: .. figure:: /asserts/medias/sdk_fig5.png :width: 800 :alt: sdk_fig5 Nuclei tools need to be downloaded for Linux **3. Tools setup** - Create *gcc*, *openocd* folders under ** directory. - Then please follow the similar steps described in **Step3** in :ref:`quickstart_setup_tools_env_windows` to extract and copy necessary files. .. note:: - Only *gcc* and *openocd* are required for Linux. - Extract the downloaded Linux tools, not the Windows version. Get and setup HBird SDK ----------------------- **1. HBird SDK download** .. code-block:: shell git clone https://github.com/riscv-mcu/hbird-sdk.git or .. code-block:: shell git clone https://gitee.com/riscv-mcu/hbird-sdk.git .. note:: - Make sure Git tool has been installed in your working machine. - After this step, the project is cloned, and the complete hbird-sdk directory is available on this machine. Assuming that the directory is **, the abbreviation will be used in the following text. **2. Build environment setting for HBird SDK** - Windows - Creat *setup_config.bat* in ** folder, and open this file with your editor, then paste the following content. .. code-block:: shell set NUCLEI_TOOL_ROOT= .. note:: The ** here indicates the path where the tools are stored as mentioned above, which should be subject to the actual situation of the user. - Open Windows command terminal and cd to ** folder, then run the following commands to setup build environment for HBird SDK, the output will be similar as the figure below. .. code-block:: shell setup.bat echo $PATH which riscv-nuclei-elf-gcc openocd make rm make help .. _figure_sdk_6: .. figure:: /asserts/medias/sdk_fig6.png :width: 800 :alt: sdk_fig6 Setup Build Environment for HBird SDK in Windows Command Line - Linux - Creat *setup_config.sh* in ** folder, and open this file with your editor, then paste the following content. .. code-block:: shell NUCLEI_TOOL_ROOT= .. note:: The ** here indicates the path where the tools are stored as mentioned above, which should be subject to the actual situation of the user. - Open Linux bash terminal and cd to ** folder, then run the following commands to setup build environment for HBird SDK, the output will be similar as the figure below. .. code-block:: shell source setup.sh echo $PATH which riscv-nuclei-elf-gcc openocd make rm make help .. _figure_sdk_7: .. figure:: /asserts/medias/sdk_fig7.png :width: 800 :alt: sdk_fig7 Setup Build Environment for HBird SDK in Linux Bash Compile Hello World demo ######################## - Enter Hello World demo folder .. code-block:: shell cd /application/baremetal/helloworld - Compile Hello World demo .. code-block:: shell make dasm SOC=hbirdv2 BOARD=ddr200t CORE=e203 DOWNLOAD=flashxip .. note:: **dasm**, this Makefile target means to compile the application, and the function of other Makefile variables are shown in the table below. .. _table_sdk_1: .. table:: Function of Makefile variables in HBird SDK build system +-----------+------------+---------------+----------------------------------------------------------------------------------------+ | Parameter | Options | Default Value | Description | +-----------+------------+---------------+----------------------------------------------------------------------------------------+ | SOC | hbirdv2 | hbirdv2 | Declare which SoC is used in application during compiling | + +------------+ + + | | hbird | | | +-----------+------------+---------------+----------------------------------------------------------------------------------------+ | BOARD | ddr200t | ddr200t | Declare which Board is used in application during compiling | + +------------+ + + | | mcu200t | | | + +------------+ + + | | hbird_eval | | | +-----------+------------+---------------+----------------------------------------------------------------------------------------+ | CORE | e203 | e203 | Declare which Core is used in application during comiling | +-----------+------------+---------------+----------------------------------------------------------------------------------------+ | DOWNLOAD | ilm | ilm | Declare the download mode of the application | + +------------+ + + | | flash | | - ilm: Program will be downloaded into ilm(itcm) and run directly in ilm | + +------------+ + + | | flashxip | | - flash: Program will be downloaded into flash, and will be copied to ilm when running | + + + + + | | | | - flashxip: Program will be downloaded into flash, and run directly in flash | +-----------+------------+---------------+----------------------------------------------------------------------------------------+ | V | 1 | NA | If V=1, it will display compiling message in verbose including compiling options | +-----------+------------+---------------+----------------------------------------------------------------------------------------+ | SILENT | 1 | NA | If SILENT=1, it will not display any compiling message | +-----------+------------+---------------+----------------------------------------------------------------------------------------+ .. _quickstart_run_hello_world: Run Hello World demo #################### **1. Hardware connection** - Connect Nuclei ddr200t development board and your computer with HBird Debugger. - Connect power supply and turn on the power switch on Nuclei dde200t development board. .. figure:: /asserts/medias/sdk_fig8.png :width: 500 :alt: sdk_fig8 Connect with PC and power supply **2. Debugger driver install** - Windows - HBird Debugger could be used without any driver installation in Windows. - Since HBird Debugger has the functionality that “convert the UART to USB”, so if you have completed hardware connection as described in **Step1**, then you will be able to see a USB Serial Port (e.g., COM8) show up in your Windows Device Manager. - Linux - After hardware connection as described in **Step1** completed, you can use the following command to check the USB status. .. code-block:: console lsusb // The example information displayed as below ... Bus 001 Device 010: ID 0403:6010 Future Technology Devices International, Ltd FT2232xxxx - Use the following command to set udev rules, to make this USB can be accessed by plugdev group. .. code-block:: console sudo vi /etc/udev/rules.d/99-openocd.rules // Use vi command to edit the file, and add the following lines SUBSYSTEM=="usb", ATTR{idVendor}=="0403", ATTR{idProduct}=="6010", MODE="664", GROUP="plugdev" SUBSYSTEM=="tty", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6010", MODE="664", GROUP="plugdev" - Add your user name into the plugdev group. .. code-block:: console whoami // Use above command to check your user name, assuming it is your_user_name // Use below command to add your_user_name into plugdev group sudo usermod -a -G plugdev your_user_name - Double check if your user name is really belong to plugdev group. .. code-block:: console groups // The example information showed as below after this command ... plugdev ... // As long as you can see plugdev in groups, then means it is really belong to. **3. Download and run** - Use the following commands to compile and download application program. .. code-block:: shell cd /application/baremetal/helloworld make upload SOC=hbirdv2 BOARD=ddr200t CORE=e203 DOWNLOAD=flash .. note:: - The ** here indicates the path where the HBird SDK project is stored as mentioned above, which should be subject to the actual situation of the user. - **upload**, this Makefile target means to compile and upload the application, and the function of other Makefile variables are shown in this table :ref:`table_sdk_1`. **3. Run result** The function of Hello World demo is to print some info in the screen of PC through UART, so the serial port display terminal should be ready first. - In Windows, there are so many serial port display terminals that can be used, such as Tera Term, PuTTY, etc. You can choose one you like, and install it, then using the following parameters to setup the UART terminal. .. code-block:: shell 115200 baud, 8 bits data, no parity, 1 stop bit (115200-8-N-1) The port number depends on your device. - In Linux, taking Ubuntu 18.04 as an example, you can use the following command to open UART terminal. .. code-block:: shell sudo screen /dev/ttyUSB1 115200 - After UART terminal opened, you can press the **MCU_RESET** button on Nuclei ddr200t development board to reset MCU and the Hello World program will be executed again, the result is shown in the figure below. .. figure:: /asserts/medias/sdk_fig10.png :width: 700 :alt: sdk_fig10 Hello World demo output .. note:: Since the application program is uploaded to MCU Flash, so you can re-execute the program by re-powering or pressing **MCU_RESET** button. Debug Hello World demo ###################### **1. Hardward connection** - Same as **Step1** in :ref:`quickstart_run_hello_world`. **2. Debugger driver install** - Same as **Step2** in :ref:`quickstart_run_hello_world`. .. note:: If the Debugger driver has been installed successfully, don't need to install it again. **3. Debug** - Use the following commands to compile application program and enter debug mode. .. code-block:: shell cd /application/baremetal/helloworld make debug SOC=hbirdv2 BOARD=ddr200t CORE=e203 .. note:: - The ** here indicates the path where the HBird SDK project is stored as mentioned above, which should be subject to the actual situation of the user. - **debug**, this Makefile target means to compile application and enter debug mode, the function of other Makefile variables are shown in this table :ref:`table_sdk_1`. - After entering debug mode, using the following GDB command, the compiled program will be uploaded, shown in the figure below. .. code-block:: shell load .. figure:: /asserts/medias/sdk_fig11.jpg :width: 800 :alt: sdk_fig11 Program download - Some commonly used GDB debugging commands are shown as following. - Set breakpoint .. code-block:: shell b main - Check breakpoint info, result shown in the figure below .. code-block:: shell info b .. figure:: /asserts/medias/sdk_fig12.jpg :width: 800 :alt: sdk_fig12 Breakpoint info - Read memory data, result shown in the figure below .. code-block:: shell x 0x80000000 x 0x80000004 x 0x80000008 .. figure:: /asserts/medias/sdk_fig13.jpg :width: 800 :alt: sdk_fig13 Memory data - Read register value, result shown in the figure below .. code-block:: shell info reg info reg mstatus info reg csr768 .. figure:: /asserts/medias/sdk_fig14.jpg :width: 800 :alt: sdk_fig14 Register value - Continue execution, stop at the breakpoint, result shown in the figure below .. code-block:: shell continue .. figure:: /asserts/medias/sdk_fig15.jpg :width: 800 :alt: sdk_fig15 Stop at breakpoint - Single step, result shown in the figure below .. code-block:: shell ni .. figure:: /asserts/medias/sdk_fig16.jpg :width: 800 :alt: sdk_fig16 Single step