How to use embARC OSP

Purpose

  • To know the concept of embARC OSP
  • To know how to run examples in embARC OSP
  • To know how to debug the examples in embARC OSP
  • To know how to create application in embARC OSP

Requirements

The following hardware and tools are required:

  • PC host
  • GNU Toolchain for ARC Processors / MetaWare Development Toolkit
  • ARC board (EM Starter Kit / IoT Development Kit)
  • embARC OSP packages

For the detailed tool requirements of embARC OSP, see Software Requirement.

Content

  • A brief introduction of embARC OSP
  • Get embARC OSP and run and debug the provided examples
  • Create an embARC OSP application

Principles

  1. IoT OS/Platform

As more and more devices are connected and become more complex, the tools running in them are becoming more and more complex.

An IoT OS is an operating system that is designed to perform within the constraints that are particular to Internet of Things devices, including restrictions on memory, size, power, and processing capacity. IoT operating systems are a type of embedded OS but by definition are designed to enable data transfer over the Internet and more other features.

  1. embARC OSP

The embARC OSP is an open software platform to facilitate the development of embedded systems based on DesignWare® ARC® processors.

It is designed to provide a unified platform for DesignWare® ARC® processors users by defining consistent and simple software interfaces to the processor and peripherals, together with ports of several well known FOSS embedded software stacks to DesignWare® ARC® processors.

For more details, see embARC OSP online documentation

  1. Other platforms

Besides embARC OSP, there are also other IoT platforms:

Steps

Get embARC OSP

  • git

The embARC OSP source code is hosted in a GitHub repository. The repository consists of scripts and other things to you need to setup your development environment, and use Git to get this repo. If you do not have Git installed, see the beginning of the OS-specific instructions for help.

Using Git to clone the repository anonymously.

# On Windows
cd %userprofile%
# On Linux
cd ~

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

You have checked out a copy of the source code to your local machine.

  • http download

You may also try to get the latest release of embARC OSP as a zip from the repository, see release page.

Run the examples

The command-line interface is the default interface to use embARC OSP. After getting the embARC OSP package, you need to open a cmd console in Windows or a terminal in Linux and change directory to the root of embARC OSP.

Use the blinky as an example.

  1. Go to the blinky example folder
cd example\baremetal\blinky
  1. Connect your board to PC host, and open the UART terminal with putty/tera term/minicom
  2. Build and run it with command, here ARC GNU toolchain is selected
# For EMSK 2.3
make TOOLCHAIN=gnu BOARD=emsk BD_VER=23 CUR_CORE=arcem11d run
# For EMSK 2.2
make TOOLCHAIN=gnu BOARD=emsk BD_VER=22 CUR_CORE=arcem7d run
# For IoTDK
make TOOLCHAIN=gnu BOARD=iotdk run

Note

For EM Starter Kit, make sure the board version (BD_VER) and core configuration (CUR_CORE) match your hardware. You could press configure button (located above the letter “C” of the ARC logo on the EM Starter Kit) when bit 3 and bit 4 of SW1 switch is off to run a self-test. By doing so, board information is sent by UART and displayed on your UART terminal.

  1. Get the results
  • For EMSK, you can see the on-board LEDs start to blink when the download is successful.
  • For IoTDK, as it does not have usable LEDs except some status LEDs, the following output log is displayed through UART.
led out: ff, ff
led out: ff00, ff
led out: ff, ff
led out: ff00, ff
led out: ff, ff
led out: ff00, ff
led out: ff, ff
led out: ff00, ff
led out: ff, ff
led out: ff00, ff
led out: ff, ff
led out: ff00, ff
led out: ff, ff
led out: ff00, ff
led out: ff, ff
.................

Debug the examples

Use the blinky as example, to debug it, you need to run the following commands:

# For emsk 2.3
make TOOLCHAIN=gnu BOARD=emsk BD_VER=23 CUR_CORE=arcem11d gui
# For emsk 2.2
make TOOLCHAIN=gnu BOARD=emsk BD_VER=22 CUR_CORE=arcem7d gui
# For IoTDK
make TOOLCHAIN=gnu BOARD=iotdk gui

For MetaWare Development Toolkit, the mdb (MetaWare debugger) is used and it is a GUI interface. You can refer the MetaWare toolchain user manual for details.

For GNU Toolchain for ARC Processors, the command-line based gdb is used. You need to have some basic knowledge of gdb debug.

Create your own application

Create your own application in embARC OSP.

  • Goals

    • Bare-metal application based on embARC OSP
    • Hardware: EMSK 2.2 - ARC EM7D Configuration / IoTDK
    • Print “Hello world from embARC” through UART at 115200 bps
    • Use GNU toolchain to running and debugging in the command line

  1. Create a folder named hello_world under embarc/example/baremetal.

  2. Copy the makefile template example/example.makefile and main.c.tmpl into hello_world folder and rename example.makefile to makefile, rename main.c.tmpl to main.c.

  3. Change the configurations in makefile according to your hardware configuration and application.

    • Change the application name: change the value of APPL to helloworld.

    • Change the board name: change the value of BOARD to emsk / iotdk. This option can also be given in command-line. If not specified, the default value is emsk

    • Change the board version: change the value of BD_VER to 22 (for emsk) or 10 (for iotdk). This option can also be given in command-line. If not specified, the default value is 22 for board emsk.

    • Change the core configuration: change the value of CUR_CORE to arcem7d This option can also be given in command-line. If not specified, the default is arcem7d for board emsk and version 22. For iotdk, CUR_CORE can be bypassed as iotdk only has one core configuration.

    • Change the embARC OSP root: change the value of EMBARC_ROOT to ../../... EMBARC_ROOT can be relative path or an absolute path.

    • Add the middleware that you need for this application: Change the value of MID_SEL.

      • The value of MID_SEL must be the folder name in <embARC>/middleware, such as common or lwip.
      • If using lwip, ntshell, fatfs, and common, set MID_SEL to lwip ntshell fatfs common.
      • Set it to common in the “HelloWorld” application.

    • Change your toolchain: change the value of TOOLCHAIN to gnu.

    • Update source folders and include folder settings.

      • Update the C code folder settings: change the value of APPL_CSRC_DIR to .. APPL_CSRC_DIR is the C code relative path to the application folder
      • Update the assembly source-folder settings: change the value of APPL_ASMSRC_DIR.
      • Update the include-folders settings: change the value of APPL_INC_DIR which is the application include path to the application folder.
      • If more than one directory is needed, use whitespace between the folder paths.

    • Set your application defined macros: Change the value of APPL_DEFINES.

      • For example, if define APPLICATION=1, set APPL_DEFINES to -DAPPLICATION=1.

Then makefile for hello world application will be like this

## embARC application makefile template ##
### You can copy this file to your application folder
### and rename it to makefile.
##

##
# Application name
##
APPL ?= helloworld

##
# Extended device list
##
EXT_DEV_LIST +=

# Optimization level
# Please refer to toolchain_xxx.mk for this option
OLEVEL ?= O2

##
# Current board and core (for emsk)
##
BOARD ?= emsk
BD_VER ?= 22
CUR_CORE ?= arcem7d

##
# Current board and core (for iotdk)
BOARD ?= iotdk
BD_VER ?= 10


##
# Debugging JTAG
##
JTAG ?= usb

##
# Toolchain
##
TOOLCHAIN ?= gnu

##
# Uncomment following options
# if you want to set your own heap and stack size
# Default settings see options.mk
##
#HEAPSZ ?= 8192
#STACKSZ ?= 8192

##
# Uncomment following options
# if you want to add your own library into link process
# For example:
# If you want link math lib for gnu toolchain,
# you need to set the option to -lm
##
#APPL_LIBS ?=

##
# Root path of embARC
##
EMBARC_ROOT = ../..

##
# Middleware
##
MID_SEL = common

##
# Application source path
##
APPL_CSRC_DIR = .
APPL_ASMSRC_DIR = .

##
# Application include path
##
APPL_INC_DIR = .

##
# Application defines
##
APPL_DEFINES =

##
# Include current project makefile
##
COMMON_COMPILE_PREREQUISITES += makefile

### Options above must be added before include options.mk ###
# Include key embARC build system makefile
override EMBARC_ROOT := $(strip $(subst \,/,$(EMBARC_ROOT)))
include $(EMBARC_ROOT)/options/options.mk
  1. Run
  • Set your EM Starter Kit 2.2 hardware configuration to ARC EM7D (no need to set to IoT Development Kit), and connect it to your PC. Open PuTTY or Tera-term, and connect to the right COM port. Set the baud rate to 115200 bps.
  • Enter make run in the command-line to run this application.

Exercises

Create your application which is different with blinky and hello_world in embARC OSP.