Creating your first embARC OSP Project - foss-for-synopsys-dwc-arc-processors/embarc_osp GitHub Wiki

Set up your development environment

  • Install selected development tools for your host development system. See link below for more information.

    The Metaware or the GNU toolchain for ARC Processors

  • Download embARC OSP source code.

    Clone the embarc_osp repository: git clone https://github.com/foss-for-synopsys-dwc-arc-processors/embarc_osp embarc_osp

    The repository will be cloned to the embarc_osp directory.

Create Project

  • Create an embARC OSP project based on an existing template

    We can create our own project directory such as myproject in embarc_osp/example.

    In this tutorial, we will do this by copying the makefile template(example.makefile) and main.c template(main.c.tmpl) in embarc_osp/example to our own project.

      cd embarc_osp/example
  mkdir myproject
  cp example.makefile myproject/Makefile
  cp main.c.tmpl myproject/main.c

    Our myproject directory now contains all the basic things needed for an embARC OSP project. We can configure the embARC OSP project makefile according to our requirements, and add extra source code folders or files to our project. When everything is configured as desired, simply type make or gmake to build the project.

make for ARC GNU, gmake for Metaware

Let's take a look at the contents of our new myproject directory.

The Makefile

Make Options for embARC OSP

  • A number of make options are defined in the embARC OSP build system for convenience and flexibly. They can be set through make command or hard-coded in the application makefile.
  • Most options are located in <embARC>/options/options.mk. Changing an option value in <embARC>/options/options.mk, will affect all applications to some extent. To set the value of options for a given application, modify the makefile for the given application.

<embARC> is the directory where embARC Open Software Platform source code located. For our project this is embarc_osp.

It is recommended to set the BOARD, BD_VER, CUR_CORE, and TOOLCHAIN options by passing them directly to the make command, for example make BOARD=emsk BD_VER=22 CUR_CORE=arcem7d TOOLCHAIN=gnu. Other make options are better hardcoded in the application makefile. These are described in more details in sections below.

Options to Set Using the make Command

  • BOARD: Select the target board.

    • The default value of this option is defined in board/board.mk.

    • Optional values as below, default value is emsk.

      BOARD Description
      emsk EM Starter Kit
      hsdk HS Development Kit
      axs AXS Board
      nsim DesignWare ARC nSIM simulator

    • For example, make BOARD=emsk selects the EMSK board as the target board.

  • BD_VER: Select the board version.

    • The default value of this option is defined in one of the following makefiles according to your BOARD option.

      BOARD Location of the definition of BD_VER
      emsk board/emsk/emsk.mk
      hsdk board/hsdk/hsdk.mk
      axs board/axs/axs.mk
      nsim board/nsim/nsim.mk

    • For the emsk board, three versions are supported in embARC: 1.1, 2.2 and 2.3. The optional values of BD_VER are 11, 22 and 23. The BD_VER must match the target EMSK version as programs built for 1.1 cannot run on an EMSK 2.0 board. The default value of BD_VER for the emsk board is 22.

      • Users of EMSK version 2.0, 2.1 and 2.2 boards will need to first upgrade the firmware version to 2.3 in order to use embARC OSP.
      • Users of EMSK version 1.0 will need to upgrade the firmware version to 1.1.
      • New firmware versions for EMSK 1.X and 2.X hardware can be obtained from [here] (https://www.synopsys.com/cgi-bin/dwarcsw/req1.cgi)

    • For the hsdk board, one version is supported: 1.0. The optional value of BD_VER is 10. The default value of BD_VER for the hsdk board is 10.

    • For the axs board, one version is supported: 103. The optional value of BD_VER is 103. The default value of BD_VER for the axs board is 103.

    • For the nsim board, only one version is supported: 1506. The optional value of BD_VER is 1506. The default value of BD_VER for the nsim board is 1506.

    • For example, make BOARD=emsk BD_VER=22 selects 2.2 as the EMSK target board version.

  • CUR_CORE: Select the core configuration for the specified board version.

    • For emsk - 11, the default value of this option is defined in board/emsk/configs/11/core_config.mk.

    • Optional values for emsk - 11; default value is arcem6.

      CUR_CORE Description
      arcem4 ARC EM4 core
      arcem4cr16 ARC EM4CR16 core
      arcem6 ARC EM6 core
      arcem6gp ARC EM6GP core

    • For emsk - 22, the default value of this option is defined in board/emsk/configs/22/core_config.mk.

    • For emsk - 23, the default value of this option is defined in board/emsk/configs/23/core_config.mk.

    • Optional values for emsk - 22; default value is arcem7d.

      CUR_CORE Description
      arcem7d ARC EM7D core
      arcem9d ARC EM9D core
      arcem11d ARC EM11D core

    • For hsdk - 10, the default value of this option is defined in board/hsdk/configs/10/core_config.mk.

    • Optional values for hsdk - 10; default value is archs38_c0.

      CUR_CORE Description
      archs38_c0 ARC HS38x4 core 0
      archs38_c1 ARC HS38x4 core 1
      archs38_c2 ARC HS38x4 core 2
      archs38_c3 ARC HS38x4 core 3

    • For axs - 103, the default value of this option is defined in board/axs/configs/103/core_config.mk.

    • Optional values for axs - 103; default value is archs36.

      CUR_CORE Description
      archs36 ARC HS36 core

    • For nsim - 10, the default value of this option is defined in board/nsim/configs/10/core_config.mk.

    • Optional values for nsim - 10; default value is arcem.

      CUR_CORE Description
      arcem ARC EM core
      archs ARC HS core

  • For nsim - 1506, the default value of this option is defined in board/nsim/configs/1506/core_config.mk.

  • Optional values for nsim - 1506; default value is arcemfull.

    CUR_CORE Description
    arcemfull ARC EM core with full features
    archs ARC HS core
    arcsem ARC EM core with secure feature

  • For example, make BOARD=emsk BD_VER=22 CUR_CORE=arcem11d selects the arcem11d core configuration for emsk 2.2.

  • TCF: Select the tool configuration file(tcf).

    • Through this option, you can choose the tcf file you provided by this option for specified board and core configuration.
    • The the tcf file you provided by this option must use absolute file path or relative file path(relative to where your application makefile located).
    • Currently, this option is not supported in nsim-1506 board, but supported in other boards.
    • For example, when the current board & core is emsk 2.3 arcem7d, then you can pass your own tcf file to replace the default. eg. There is arcem.tcf file in the folder where application's makefile located, you can run gmake BD_VER=23 CUR_CORE=arcem7d TCF=arcem.tcf to do this.
    • When you specify you own tcf file, you need to clean the project first before build it.

  • TOOLCHAIN: Select the toolchain to compile the embARC software.

    • The default value of this option is defined in options/options.mk.

    • Optional values below; default value is mw.

      TOOLCHAIN Description
      mw MetaWare Development Toolkit
      gnu ARC GNU Development Toolchain

    • For example, make BOARD=emsk BD_VER=22 CUR_CORE=arcem11d TOOLCHAIN=gnu selects the ARC GNU toolchain to compile embARC applications for emsk 2.2 arcem11d.

  • DIG_NAME: Specify the Digilent USB JTAG name.

    • The default value of this option is defined in options/options.mk.
    • This option's default value is empty. It is not necessary to set it when only one JTAG is connected to your PC. It is useful if more than one EMSK JTAG cable is connected to your PC, for example, to debug two EMSK boards using one PC.
    • This option is only available when the MetaWare toolkit is selected. This option is a simple wrapper of the -prop=dig_device=name option of the MetaWare debugger (mdb). See the MetaWare Debugger User's Guide for details.

  • V: Control whether to show verbose compiling information.

    • The default value of this option is defined in options/options.mk.
    • This option is rarely used, and its default is 0.
    • 0 means just show basic compiling information; 1 means show verbose information.

Options to Hard-Code in the Application Makefile

  • OLEVEL: Select the compiler optimization level. Possible choices are O, O0, O1, O2, O3, Os, Os1, Oz, Ofast, Og, or you can leave the OLEVEL blank to not select any optimization, like OLEVEL= .

    • The default value of this option is defined in options/options.mk.
    • For example, make BOARD=emsk BD_VER=22 CUR_CORE=arcem11d TOOLCHAIN=gnu OLEVEL=O2 selects optimization level O2 of the ARC GNU toolchain to compile embARC applications for EMSK 2.2 and arcem11d.

  • JTAG: Select the JTAG probe to load and debug the target program.

    • The default value of this option is defined in options/options.mk.

    • Optional values below; the default value is usb.

      JTAG Description
      usb Digilent USB JTAG cable
      opella Ashling Opella-XD JTAG probe

    • For example, make BOARD=emsk BD_VER=22 CUR_CORE=arcem11d OLEVEL=O2 TOOLCHAIN=gnu run selects the ARC GNU toolchain to compile embARC applications with optimization level O2 for EMSK 2.2 arcem11d, and load the applications using Digilent USB JTAG (default).

    • opella is only supported for the MetaWare Development Toolkit.

  • OS_SEL: Select operating system.

    • This option should be defined in your application makefile.

    • Set this option in the makefiles of the examples if OS services are required.

    • Optional operating system values are shown below.

      OS_SEL Description
      freertos FreeRTOS Runtime

    • If you leave the OS_SEL value blank, such as OS_SEL= , no OS services are selected; just use baremetal runtime.

    • For developing different run-time applications with embARC OSP, it is helpful to review the examples in <embARC>/example.

  • MID_SEL: Select middleware to be used in embARC OSP-based application.

    • This option should be defined in your application makefile.
    • All available middleware is located in <embARC>/middleware.
    • It is recommended to include common middleware to provide basic printf() functionality using xprintf().

  • LIB_SEL: Select libraries to be used in the embARC OSP-based application.

    • This option should be defined in your application makefile.

    • All available libraries are located in <embARC>/library.

    • clib is the default.

    • Optional library values are shown below.

      LIB_SEL Description
      clib C Library Support
      secureshield SecureShield Library

  • APPL_LIBS: Set extra required application libraries to be linked.

    • This option should be defined in your application makefile.
    • This APPL_LIBS option collects extra linker option to include extra libraries to be linked.
    • For example, APPL_LIBS = -lm means linking math library to target program, -lm is only supported with GNU toolchain

  • HEAPSZ: Set application heap size in bytes.

    • This option should be defined in your application makefile.
    • The default value of this option is defined in options/options.mk.
    • The default value is 8192, which means the heap size of the application is set to 8192 bytes by default.
    • For baremetal and Contiki applications, this HEAPSZ configuration is useful.
    • For FreeRTOS applications, you can define the RTOS heap size by setting configTOTAL_HEAP_SIZE in FreeRTOSConfig.h.

  • STACKSZ: Set application stack size in bytes.

    • This option should be defined in your application makefile.
    • The default value of this option is defined in options/options.mk.
    • The default value is 8192, which means the stack size of the application is set to 8192 bytes by default.
    • For baremetal and Contiki applications, this STACKSZ configuration is useful.
    • For FreeRTOS applications, you can define the minimum RTOS task stack size by setting configMINIMAL_STACK_SIZE in FreeRTOSConfig.h, and define each task's stack size in the application source code.

  • USE_BOARD_MAIN: Control which board init process is used.

    • The default value of this option is defined in board/board.mk.
    • Default value is 1; set in <embARC>/board/board.mk.
    • When this option is 0, it uses the normal board init process, compatible with previous embARC OSP releases; you must do board_init yourself.
    • When this option is 1, embARC OSP initializes fatfs, ntshell, and lwip with WiFi and creates a FreeRTOS task for main(). You only need to write applications or create new tasks in the main() function. When ntshell is enabled, the main() function needs to be triggered by the ntshell main command.
    • For more details about how this new process is implemented, see <embARC>/board/board.c.
    • In most cases, you don't need to change this value to 0.

  • WIFI_SEL: Set WiFi module used in the examples.

    • The default value of this option is defined in board/board.mk.

    • Optional values for WIFI_SEL are shown below.

      WIFI_SEL Description
      0 PmodWiFi (default)
      1 RW009 WiFi

  • EMBARC_ROOT: Set embARC OSP source code root directory path.

    • This option should be defined in your application makefile.
    • This option specifies the path of the embARC OSP source code root.
    • The path can be relative or absolute.

  • embARC application related options

    • These options should be defined in your application makefile.

    • APPL: Set embARC application name.

    • APPL_CSRC_DIR: Set the path of application C source code directories used.

      • All used c source code directory paths including sub-folders need to be added.
      • C source code files should be suffixed with c or C, such as *.c or *.C.
      • The paths are separated by whitespace.

    • APPL_ASMSRC_DIR: Set the path of application assembly source code directories used.

      • All used assembly source code directory paths including sub-folders need to be added.
      • Assembly source code files should be suffixed with s or S, such as *.s or *.S.
      • The paths are separated by whitespace.

    • APPL_INC_DIR: Set the path of application include-file directories used.

      • All used include-file directory paths including subfolders need to be added.
      • The paths are separated by whitespace.

    • APPL_DEFINES: Set extra macros defined from makefile for this application.

      • The macro definitions are separated by whitespace.
      • For example, if you want to define USE_EMBARC=1, then you should set the value to -DUSE_EMBARC=1.

    • Additional compiler, assembler, and linker options.

      • ADT_COPT: Additional compiler options; see the compiler manual for help.
      • ADT_AOPT: Additional assembler options; see the assembler manual for help.
      • ADT_LOPT: Additional linker options; see the linker manual for help.

The main.c

In the main.c, there is only one main function entry for embARC OSP project. You can use the APIs provided by embARC OSP, or from third party middlewares or libraries.

Cross Reference

embARC - Accelerate software development of embedded systems based on DesignWare ARC processors

Homepage | GitHub | Developers Forum

⚠️ **GitHub.com Fallback** ⚠️