Skip to content

Latest commit

 

History

History
226 lines (156 loc) · 11.5 KB

CONTRIBUTING_APPLICATIONS.md

File metadata and controls

226 lines (156 loc) · 11.5 KB
Raw

How to Contribute to embARC Applications

embARC users are welcome to make contributions to embARC, including examples, source code (bug fixes and/or new packages), and documentation. This document is intended to help you contribute to embARC Applications quickly.

Prerequisites

The hardware we used during development is EM Starter Kit(aka EMSK). We need to download and install the following tools:

  • Download and install Development Tools.

    gnu_make

  • Download and install Digilent Adapt Software, driver for Digilent JTAG-USB cable.

    digilent_adapt

  • Download and install Zadig, replacing a driver for Windows host.

    zadig

    Notices: To do that, you have to connect EMSK to PC using JTAG-USB cable. Then click on the Options - List all devices, and you can find Digilent USB Device(Interface 0/1). Just replacing Digilent USB Device(Interface 0) to WinUSB driver, it helps PC to load executable file into EMSK.

    You can see Digilent USB Device in the Device Manager if the driver has been installed successfully.

    device_manager

  • Get embARC OSP and embARC Applications source code.

    • Get a Github Account. Download and install Git，and you have to learn how to develop projects using git. See Git Book for reference.
    • Download the embARC OSP and rename it to embarc_osp.
    • Fork the embarc_applications to your own repo. You will develop the project based on that in your host.

    fork_app_repo

    • Goto the folder ./embarc_osp. Run the Git Bash and type the following commands to clone embARC Applications source code to ./embarc_osp/application folder:

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

    Then, you can see there are serval applications existing in this folder, such as aws_iot_smarthome, aws_iot_smarthome_multinode, etc.

  • Download and install Doxygen for building embARC document.

    Goto the path: ./embarc_osp/doc, run the Command Line and use the following commands to make embARC document.

    document_folder

    doxygen_make

    A few minutes later, you can open the embARC_Document.html using browser.

    embarc_document

  • Download and install Tera Term.

Getting Start with Existing Application

We provided some examples and applications in embARC, user can take reference from them.

Here we take bootload example using GNU and EMSK 2.2, EM11D for example. Goto the path: .\embarc_osp\example\baremetal\bootloader, run the Command Line and type commands for building and running.

cmd_make

Run the Tera Term:

tera_term

For more detail information, see Getting Started with embARC Using GNU on Windows for reference. And see Getting Started with embARC OSP to learn how to get start with embARC using different toolsets or hosts.

Creating a New Application in embARC

See the document Example Usage Guide - ./embarc_osp/doc/embARC_Document/html/page_example_usage.html in the embarc_osp for more detail information. It will help you to create a Hello World application using ARC GNU quickly.

example_usage_guide

Developing Your Application Using Git

  1. Make sure you have installed Git，and know how to use it.

  2. Goto the folder ./embarc_osp/application, create a new folder for your own application, like smart_device. Please notice that your application projects should be placed under the folder ./embarc_osp/application, not ./embarc_osp/example.

  3. Copy example.makefile and main.c.tmpl in ./embarc_osp/example folder to the newly created smart_device folder.

    • Rename example.makefile to makefile.
    • Rename main.c.tmpl to main.c.
    • Change the configurations in makefile according to your hardware configuration.
    • Modify your main.c.
    • Compile this application on the command line.
    • Run or debug this application. See the document Example Usage Guide in the embARC OSP documentation for more information.

    Notices: All C source code must adhere to Linux Kernel Coding Style. The source-code files in embARC are documented with C-style code comments and Doxygen-based comments. A Doxygen comment example is shown below:

    /**
 * \defgroup    EMBARC_APP_TMPL         embARC Template Example
 * \ingroup     EMBARC_APPS_TOTAL
 * \ingroup     EMBARC_APPS_BOARD_EMSK
 * \ingroup     EMBARC_APPS_BAREMETAL
 * \brief       embARC Example for template

 * \details
 * ### Extra Required Tools

 * ### Extra Required Peripherals

 * ### Design Concept

 * ### Usage Manual

 * ### Extra Comments

*/

/**
 * \file
 * \ingroup     EMBARC_APP_TMPL
 * \brief       main source of template example
 */
/**
 * \addtogroup  EMBARC_APP_TMPL
 * @{
 */
/* embARC HAL */
#include "embARC.h"
#include "embARC_debug.h"
/** main entry */
int main(void)
{
        EMBARC_PRINTF("Hello embARC from template example\r\n");
        return E_SYS;
}
/** @} */

  4. Developing your application using Git. See Git Book for learning how to use it.

Committing Your Work

You can contribute your work by submitting Pull Request to embarc_applications in github after finishing your project development. Creating a new Pull Request:

new_pull_request

Choose to compare across forks:

compare_across_forks

Choose compare changes:

compare_changes

Create the new pull request:

create_pull_request

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.