Demo project

ZStudio contains a number of demos which can be imported directly. The following sections walk you through the demo projects and describe a set of ZStudio features along the way.

Hello_with_dsp_and_nn_sdk_0.4.0

Hello_with_dsp_and_nn demo exported from the Nuclei IDE, which includes the dsp and nn libraries in the Nuclei SDK v0.4.0. In the sections below, this demo is adopted as an example for step by step instructions on how to run and debug demo project on board.

Import demo project

Steps to import the demo into ZStudio:

1. On the ZStudio main menu, click File > Import Makefile Project from the pull-down menu.
2. On the invoked Import dialog, specify the Project Root Path of hello_with_dsp_and_nn_sdk_0.4.0 demo.
3. To specify the Entry Makefile, click browse button to search for the Makefile under to the hello_with_dsp_and_nn_sdk_0.4.0\Debug..
4. Click Import and make a selection between open it in current window or in new window.
5. Find the imported demo project in the Solution Explorer.

Modify project configuration

To build the demo project in ZStudio, you need to fix directory path and some some incompatible options in build configuration.

1. Click Fix Makefile project in the dialog prompted from message window.

   

2. Fix directory path of demo project:

   Replace all /home/tptuser/NucleiStudio_workspace/hello_with_dsp_and_nn_sdk_0.4.0 with .

3. Modify build configurations due to incompatibilities between ZCC and GCC:

   • Remove all -mtune=nuclei-300-series
   • Remove all stdc++ library. ( you need to delete the following JSON ,{"value":"stdc++"})
   • Specify --target=riscv32-unknown-elf to compiler and linker.
   • Replace all --specs=nano.specs --specs=nosys.specs option with --config nano.cfg option.

And your fix dialog will be like the below figure. Click Apply to complete the update.

tip

Search and select Fix Makefile Project in Command Palette (Ctrl+Shift+P) can evoke the window again.

Build the demo

1. Select Debug configuration and click the button in Project Controller view to build the demo project.

2. Check the success of the build process in the Build Console view, you can filter the build information in the drop-down box.

3. Verify output file under output node in Project Navigator or hello_with_dsp_and_nn_sdk_0.4.0\output\debug in File Navigator.

   

Run and debug the demo on board

1. Connect a board to your computer with a USB adapter, make sure the USB is really be recognized by the PC.

   Check if the board need Driver. Please visit Nuclei Board Labs to install the Driver for N300 on Linux or Window PC.

2. Create serial port connect

   From the main menu, select View > Serial Port Monitor to invoke the view. Click the + button to configure the port settings, the Serial Port box automatically detects any communication port connected to your computer. Click OK to build the connect. Check if the status icon becomes green.

   

   The status icon becomes green means Serial Port connect successfully. And the disconnect of board may cause serial port connect failure and the status icon will become red.

   

3. Add OpenOCD configuration and start OpenOCD.

   From the main menu, select View > OpenOCD Explorer, click + to create an OpenOCD configuration. In the settings, you need to specify OpenOCD executable and configuration file. To use Nuclei N300 Development Board:

   
   • You can download OpenOCD executable (2022.12 and higher version is recommended) on Nuclei website.
   • OpenOCD configuration file is under the demo project directory ${projectPath}/nuclei_sdk/SoC/demosoc/Board/nuclei_fpga_eval/openocd_demosoc.cfg

   Right-click the exist OpenOCD and select start or stop in context menu to start or end the OpenOCD process, the status icon becomes green means OpenOCD process is on.

   
   tip

   Turn off or disconnect the board may cause the disconnection of OpenOCD and your board despite the OpenOCD process signal is green. Please check and restart OpenOCD.

4. Specify run and debug configuration

   On the Project Controller, click the the (Run/Debug Configuration) button to invoke configuration wizard. Set Board as run and debug target and select the OpenOCD configuration that matches the board you connected.

   

5. Back to the Solution Explorer view and click button and check the project output in Serial Port Monitor view.

   

6. Add a breakpoint and start debug session. The debugger runs to the first breakpoint it encounters and stops. Click Step Over button and check the project output in Serial Port Monitor view.

   

AccInst

AccInst demo is adopted as an example for step by step instructions on how to launch a profile session to identify bottlenecks and optimize source code.

Open AccInst solution

Steps to open the demo in ZStudio:

1. On the ZStudio main menu, click File > Import Example Solutions. Select AccInst from pull-down box and click Open.

2. Check the Normal project and Accelerated project in the AccInst solution in ZStudio.

   Compared to Normal project, Accelerated project has optimized source code by adding accelerated instruction.

   

Build

Steps to build Normal and Accelerated project:

1. Set the Normal project as active project, select the Debug configuration and RISC-V platform, then Click Build button and Check the success of the build process in the Build Console view.

   

2. Set the Accelerated project as active project and reserve other configuration, then Click Build button and Check the success of the build process in the Build Console view.

   

Launch profiling sessions

Steps to launch profiling sessions for both Normal and Accelerated projects with default configurations:

1. Set the Normal project as active project, select Profiling > Start Profiling from main menu. Once starting profiling, you should wait for the The profiling has finished! prompted from message window and profiling results will be opened in editor.

   

2. Set the Accelerated project as active project, select Profiling > Start Profiling from main menu. Once starting profiling, you should wait for the The profiling has finished! prompted from message window and the profiling results will be opened in editor.

   

Compare profiling result

According to the Function Summary, the bottleneck function is tpt_mat_cmplx_mult_q15. The function tpt_mat_cmplx_mult_q15 contains a three-tier nested for loop. The innermost loop performs matrix multiplications. Since the innermost loop is where the most CPU time is spent, optimizing the performance of the tpt_mat_cmplx_mult_q15 function potentially lead to overall performance improvements for the code.

To use profiling results comparison tool and see how changes that you've made affect performance:

1. On the main menu, select View > Profiling Comparison to invoke the comparison tool.

2. In the profiling comparison side bar, you need to specify Normal project profiling result as the reference benchmark. Right-click and select Select as Base.

   

3. Click the button to invoke the configuration window. And click "Ok" when you are happy with the configuration.

   • Select the data visualization of the Program Performance Comparison: select at least one form between chart and table.
   • Select items to compare. The default items are Instruction Count, Cycle Count and Instruction Per Cycle. You can select by yourself.

4. Use Shift or Ctrl to select two profiling results, right click on one, and select Compare to achieve quick compare.

   

5. The profiling comparison view will be opened in editor.

   

The decrease of self cycle and self instruction of tpt_mat_cmplx_mult_q15 as well as Cycle Count and Instruction Count of Accelerated project demonstrate that optimizing the performance of the tpt_mat_cmplx_mult_q15 function improves overall performance and efficiency.

HPMicro Demo

This section provides step by step instructions on how to use the HPM Tool for one-stop embedded development in ZSolution, using sample projects from the HPMicro SDK.

Importing the HPMicro SDK

To import the HPMicro SDK sample projects into ZSolution:

1. First, generate the HPMicro SDK, Please download version 1.6.0 or later since the HPM SDK officially supports the Terapine's ZCC toolchain starting from version 1.6.0.

2. In the menu bar, select File > Import CMake Project, and configure it in the popup window.

   • Project Root Directory: Choose the local root directory where the HPMicro SDK is saved.
   • CMake Working Directory: Specify here the desired location for the generated CMake files. It's recommended to create a build folder under the SDK's sample/hello_world directory and input here the absolute path to the new build folder.
   • CMake Arguments: Specify the full CMake parameters required to generate the project, such as -DBOARD=hpm5300evk .. indicates that the target program is to be built for the hpm5300evk development board.
   • Environment Variables: Click + to add the environment variables passed to CMake during the import process.
     • Absolute path to the toolchain directory: GNURISCV_TOOLCHAIN_PATH={Absolute_path_of_your_zcc_toolchain_directory}
     • Use the ZCC toolchain for compilation: HPM_SDK_TOOLCHAIN_VARIANT=zcc
     • Absolute path to the SDK root directory: HPM_SDK_BASE={Absolute_path_of_your_SDK_top-level_folder}

3. Click Import and monitor the progress in the run console. Once successfully imported, the Project Navigation pane will display three projects: hpm_sdk_gcc_lib, hpm_sdk_lib, and demo.

   

Configuring pins with HPM Tools

ZSolution integrates HPMicro Tools (Pinmux and Clock Tool) to support direct MCU pins and clock configuration within ZStudio while developing applications. In this demo we are going to show you how to light an LED with GPIO pins.

1. In the menu bar, select Tools > HPM Tools to access the HPMicro Tools page. Select the target development platform SoC as "HPM5361" and the Package as "LQFP100." Click Create Project to enter the configuration interface, where you can configure the pins and clock.

   

2. Refer to the HPM5300EVK Board Diagram. For example, the anode of LED2 is connected to 3.3V, and the cathode is connected to the PA23 I/O pin. Setting PA23 to low will light up the LED, while setting it to high will turn it off.

   

3. In ZSolution, click the PA23 pin and, in the popup, select GPIO.A[23]. Set the GPIO properties: set the direction to "Output," the output level to "High," and choose "GPIO0" as the GPIO Controller. Click "OK."

   

4. Click Code Preview at the top-right corner to view the pin configuration initialization code generated by the HPM Pinmux Tool (.c and .h files). Since the .h file already exists in the HPM SDK, only the .c file needs to be applied to the project.

   

5. The source file names and function names generated by the HPM Pinmux Tool conflict with those in the SDK. To avoid conflicts, this demo only copies the pin configuration initialization code provided by the HPM Pinmux Tool. In the imported demo project, delete helloworld.c. Then, create a main.c file and use the generated configuration code in main.c.

   main.c

   /*
   * Copyright (c) 2021 HPMicro
   *
   * SPDX-License-Identifier: BSD-3-Clause
   *
   */
   
   #include <stdio.h>
   #include "board.h"
   #include "hpm_debug_console.h"
   #include "hpm_gpio_drv.h"
   #include "hpm_gpiom_drv.h"
   
   static void init_pins_led(void)
   {
      // Pin initialization code generated by HPM Pinmux Tool
      HPM_IOC->PAD[IOC_PAD_PA23].FUNC_CTL = IOC_PA23_FUNC_CTL_GPIO_A_23;
   
      gpiom_set_pin_controller(HPM_GPIOM, GPIOM_ASSIGN_GPIOA, 23, gpiom_soc_gpio0);
      gpio_set_pin_output(HPM_GPIO0, GPIO_OE_GPIOA, 23);
      gpio_write_pin(HPM_GPIO0, GPIO_DO_GPIOA, 23, 1);
   }
   
   int main(void)
   {
      board_init(); // Initialize the development board
   
      init_pins_led(); // Initialize the GPIO for the LED
   
      while(1)
      {
         gpio_write_pin(HPM_GPIO0, GPIO_DO_GPIOA, 23, 0); // Set pin low to turn on LED
         board_delay_ms(500);
         gpio_write_pin(HPM_GPIO0, GPIO_DO_GPIOA, 23, 1); // Set pin high to turn off LED
         board_delay_ms(500);
      }
      return 0;
   }

As shown in the code above, the main function calls the SDK's board_init function to initialize the board's peripheral clocks and some I/Os. It then calls init_pins_led to initialize the GPIO in the HPM Pinmux Tool-generated code. In the while loop, the gpio_write_pin function sets the PA23 I/O pin's level, and the board_delay_ms function is used to alternate the LED's blinking.

Program Compilation and Flashing

ZSolution supports program flashing via OpenOCD.

1. Build the project: Set "demo" as active project and click Build. Check build process in Build Console and verify the output file.

   

2. Add and start OpenOCD: Download the HPMicro OpenOCD, find the OpenOCD and boards configuration files for Windows or Linux systems.

   Select OpenOCD Explorer from the View dropdown menu, click the + button to create an OpenOCD configuration, and specify the location of the OpenOCD executable and configuration file on your PC.

   

   Here, we are using the hpm5361evk development board, and there are two configuration files: hpm6750-single-core.cfg and ft2232.cfg. You need to add the absolute paths of these two files to the configuration files pane.

3. Right-click the added OpenOCD to start or stop the current OpenOCD process. A green status light indicates that the OpenOCD process is running.

   

4. In the run configuration, select the connection target as "Development Board" and choose the OpenOCD configuration created in the previous step. Click Run and you should see the LEDs on the development board alternately blinking.