2017.03
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
embARC Introduction

Overview

embARC is an open software platform to facilitate the development of embedded systems based on ARCv2 processors.

embARC provides a solid starting foundation for embedded developers, simplifying development and improving time-to-market through software reuse.

The embARC software includes the following components:

  • ARC Hardware Abstraction Layer (HAL) provides the necessary hardware abstraction for ARCv2 ISA compatible processors.
  • Device Hardware Abstraction Layer (HAL) provides hardware abstraction for common platform devices and implementation of DesignWare IP drivers, such as UART, IIC, and SPI.
  • Board Support Package (BSP) Layer provides support for different boards based on the ARCv2 processors.
  • OS Layer provides embedded operating-system support, including options for both traditional Real-Time Operating Systems (RTOSs) and lightweight Internet of Things (IoT) OSs.
  • Library Layer provides basic common library support for embedded systems, such as C library, dlmalloc library and SecureShield library.
  • Middleware Layer includes mainstream embedded software-stack solutions, including FAT file system, network stack, simple shell/Command Line Interface (CLI), IoT protocols, lightweight graphics, IoT cloud connectivity and more.

    Many examples, covering IoT, network, and sensor application cases, are also provided to help get started quickly with ARCv2 processors and the embARC software.

    Note
    See the Related Pages section of the embARC documentation for more information on individual embARC components.

    embARC

    embARC Architecture

    Note
    Dotted lines indicate supported packages not included in the embARC OSP distribution. See the related embARC documentation sections for information on how to obtain these packages for use with embARC.
    For secure communications, see Middleware - TLS/DTLS Support.
    For MQX support, See OS - MQX.

Purpose and Scope

embARC is an open software platform, providing useful components with a consistent software layering model and interfaces to ARCv2 processors for portability and reusability. Developers can write software based on embARC to accelerate implementation and reduce their learning curve and the time-to-market of final product implementation.

The goals of embARC are as follows:

  • Provide an easy introduction for new users of ARC processors.
  • Provide useful software stacks as a starting point for building embedded products based on ARC and well-known open-source software packages.
  • Provide broad ranges of examples to demonstrate ARC usage in various embedded IoT applications.
  • Provide simple, frictionless out-of-the box user experience through:
    • Single archive download containing all embARC packages and examples.
    • Comprehensive pre-integrated tools support
    • Clear, simple, and extensive how-to instructions.

embARC Software Package

The table below describes the embARC Software Package directory structure and sub-folders and provides a high-level description of the contents of each sub-folder.

embARC folder Usage and Meanings
arc ARC processor-related core services such as startup, interrupt/exception handling, timer, cache, uDMA, and built-in functions
board Different board support packages for ARC cores based on the device HAL
device Device HAL definition and common device drivers
example embARC examples for bare metal, FreeRTOS, Contiki
ide_projects Pre-generated Eclipse projects for all embARC examples with either GNU or MetaWare IDE
inc Common header files for embARC, such as ARC core-related headers and other common headers
lib Library support for embARC, such as C library, dlmalloc, ya_getopt and SecureShield
middleware Middleware support for embARC, like LwIP, CoAP, MQTT
options Build system based on makefiles
os OS support for embARC, such as FreeRTOS and Contiki

Tools Support

The embARC software is supported by the following toolchain offerings from Synopsys:

  • The DesignWare® ARC® MetaWare Development Toolkit builds upon a 25-year legacy of industry-leading compiler and debugger products. It is a complete solution that contains all the components needed to support the development, debugging, and tuning of embedded applications for the DesignWare ARC processors.
  • The GNU Toolchain for DesignWare ARC Processors provides a prebuilt GNU Toolchain for ARC Processors integrated into the Eclipse IDE. The GNU tools are maintained by Synopsys with new releases being published at regular intervals.
  • The DesignWare® ARC® MetaWare Development Toolkit Lite Edition is a functioning demonstration of the MetaWare Development Toolkit, but has a number of restrictions, including a code-size limit of 32 Kb and no run-time library sources. It is available for free download and use for academic, personal, and noncompetitive evaluation purposes.

Build System

The embARC build system is based on the makefile system as shown below. To add new components, add a new makefile to the system. All embARC components are compiled into libraries, which are then merged into one final library called libembarc.a. The application objects are then linked against libembarc.a to produce the target .elf file.

embARC Build System

embARC Build System

The options directory under the embARC root contains the common makefiles as shown below:

Makefile Names Description
debug.mk Target debug options for the MetaWare debugger, which supports Ashling OpellaXD and Digilent USB-JTAG connections
files.mk Files and directory collections in embARC
options.mk Entry makefile with common definitions, path definitions, other makefiles, and so on.
rules.mk Make targets and rules
scripts.mk Common makefile functions
toolchain.mk General definitions for toolchain, including toolchain_gnu.mk for ARC GNU toolchain and toolchain_mw.mk for MetaWare toolchain
toolchain_gnu / toolchain_mw.mk Core independent compile and link options

Coding Style

The embARC coding style is inspired by the Linux Kernel Coding Style. Variable naming such as "xxx_yyy_zzz" represents a paradigm of objective_action_target, for example uart_get_info (UART GET INFORMATION). Abbreviations in embARC are as follows.

Abbreviation Word
AUX aux Auxiliary Register
BCR bcr Build Configuration Register
DEV dev Device
EXC exc Exception
INT int Interrupt
INFO info Information

The source-code files in embARC are documented with C-style code comments and Doxygen-based comments. A Doxygen comment example is shown below:

1 /**
2  * \defgroup EMBARC_APP_TMPL embARC Template Example
3  * \ingroup EMBARC_APPS_TOTAL
4  * \ingroup EMBARC_APPS_BOARD_EMSK
5  * \ingroup EMBARC_APPS_BAREMETAL
6  * \brief embARC Example for template
7 
8  * \details
9  * ### Extra Required Tools
10 
11  * ### Extra Required Peripherals
12 
13  * ### Design Concept
14 
15  * ### Usage Manual
16 
17  * ### Extra Comments
18 
19  */
20 
21 /**
22  * \file
23  * \ingroup EMBARC_APP_TMPL
24  * \brief main source of template example
25  */
26 
27 /**
28  * \addtogroup EMBARC_APP_TMPL
29  * @{
30  */
31 /* embARC HAL */
32 #include "embARC.h"
33 #include "embARC_debug.h"
34 
35 /** main entry */
36 int main(void)
37 {
38 
39  EMBARC_PRINTF("Hello embARC from template example\r\n");
40 
41  return E_SYS;
42 }
43 /** @} */

How to Contribute to embARC

embARC users are welcome to make contributions to embARC, including examples, source code (bug fixes and/or new packages), and documentation.

How to Contribute to Documentation

embARC html documentation is generated from documents in the doc/documents folder and comments in source files using Doxygen. All documents are written in plain text and formatted using Doxygen and HTML syntax. They can easily be edited; the files have the extension .doc. The documents for each component are in their specific sub-folder. xxx_declaration.doc is mainly for the modules in Doxygen. xxx_description.doc is used to generate independent pages with general descriptions. All the .doc files are declared and called by the Doxygen configuration file, embARC.doxyfile.

For the source code comment format, see similar embARC source code for reference.

How to Add New Examples

See Adding a New embARC Example

How to Add New Devices

See Adding New Device to embARC

How to Add New Boards

See Adding New Board to embARC

How to add new OSs

See Adding a New OS to embARC

How to Add Mew Middleware

See Adding New Middleware to embARC

How to Commit Your Work

You can contribute your work by submitting a post with your patches as an attachment to the embARC Forum - Enhancements. First you need to register an account on the embARC Forum.

Copyright Notice

Copyright (c) 2017, Synopsys, Inc. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1) Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2) Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3) Neither the name of the Synopsys, Inc., nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. NY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

For complete embARC license information, please refer to the embARC FOSS Notice License.