embARC Open Software Platform

https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/
Admin
embARC OSP is an open-source software platform for ARC processors that provides operating systems,...
Tokens:30,623
Snippets:193
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Navigate to blinky Example Directory

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/getting_started/getting_started

This command changes the current directory to the location of the 'blinky' example within the embARC OSP source code. This is a necessary step before building the example application.

```bash
cd embarc_osp\example\baremetal\blinky
```

--------------------------------

### Run blinky Example for EMSK 2.3

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/getting_started/getting_started

This command executes the 'blinky' example application after it has been successfully built. It uses the same parameters as the build command and includes the 'run' target. This will deploy and run the application on the specified hardware.

```bash
cd embarc_osp\example\baremetal\blinky
make TOOLCHAIN=gnu BOARD=emsk BD_VER=23 CUR_CORE=arcem11d run
```

--------------------------------

### Build blinky Example for EMSK 2.3

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/getting_started/getting_started

This command initiates the build process for the 'blinky' example application. It specifies the GNU toolchain, the target board (EMSK), the board version (2.3), and the core (arcem11d). This command is typically executed after navigating to the example's directory.

```bash
make TOOLCHAIN=gnu BOARD=emsk BD_VER=23 CUR_CORE=arcem11d
```

--------------------------------

### Build and Run Blinky Example (MetaWare)

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/board/emsdp

This snippet shows the command to build and run the 'blinky' example using the MetaWare toolchain. It assumes you are in the example directory and specifies the board, revision, core, and toolchain.

```shell
cd <embarc_root>/example/baremetal/blinky
gmake BOARD=emsdp BD_VER=rev2 CORE=em11d_dfss TOOLCHAIN=mw run
```

--------------------------------

### Interactive Program Startup Notice (GPL)

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/license/license

Example of a short notice to display when an interactive program starts, informing users about its licensing, warranty, and redistribution terms under the GNU GPL.

```text
Gnomovision version 69, Copyright (C) year name of author
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w’.
This is free software, and you are welcome to redistribute it under certain conditions; type `show c’ for details.
```

--------------------------------

### Build Hello World Example (MetaWare/ARC GNU)

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/bsp/bsp_build_cmd

Commands to initiate the build process for the 'hello world' example. 'gmake' is used for the MetaWare toolchain, and 'make' is used for the ARC GNU toolchain.

```bash
# MetaWare
gmake
# ARC GNU
make
```

--------------------------------

### EmbARC Makefile Example Usages

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/getting_started/makefile_manual

These examples demonstrate how to use the make system with various configurations. They show building with default settings, specifying multiple configuration parameters, and using a custom TCF file.

```makefile
make all

```

```makefile
make BOARD=emsk BD_VER=22 CUR_CORE=arcem7d OLEVEL=O2 TOOLCHAIN=gnu all

```

```makefile
make BOARD=emsk BD_VER=22 CUR_CORE=arcem7d TCF=mytcfpath all

```

--------------------------------

### Build Blinky Example for SD Card (MetaWare)

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/board/emsdp

This snippet shows the command to build the 'blinky' example for deployment on a micro-SD card using the MetaWare toolchain. The output binary is intended to be renamed to 'app.bin'.

```shell
cd <embarc_root>/example/baremetal/blinky
gmake BOARD=emsdp BD_VER=rev2 CORE=em11d_dfss TOOLCHAIN=mw bin
```

--------------------------------

### Clone embARC OSP Repository using Git

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/getting_started/getting_started

This command clones the embARC OSP source code from its GitHub repository. It requires Git to be installed on your system. The command sets the current directory and then clones the repository into a directory named 'embarc_osp'.

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

```batch
cd %userprofile%
git clone https://github.com/foss-for-synopsys-dwc-arc-processors/embarc_osp.git embarc_osp
```

--------------------------------

### Create Symbolic Link for Example Folder

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/developer/documentation_generation

Creates a symbolic link named 'example' that points to the '..<0xC2><0xA0>..\..\..\example' directory. This is often used to link documentation source files or build directories.

```bash
>mklink /D example ..\..\..\example
symbolic link created for example <<===>> ..\..\..\example
```

--------------------------------

### Build and Run Examples with MetaWare Toolchain

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/developer/application_development

These commands are used to build, run, debug, and manage build configurations for embARC OSP examples using the MetaWare toolchain. They specify the board, board version, core, and toolchain.

```bash
gmake BOARD=emsk BD_VER=22 CUR_CORE=arcem7d TOOLCHAIN=mw
```

```bash
gmake BOARD=emsk BD_VER=22 CUR_CORE=arcem7d TOOLCHAIN=mw JTAG=usb run
```

```bash
gmake BOARD=emsk BD_VER=22 CUR_CORE=arcem7d TOOLCHAIN=mw JTAG=usb gui
```

```bash
gmake BOARD=emsk BD_VER=22 CUR_CORE=arcem7d TOOLCHAIN=mw JTAG=usb bin
```

```bash
gmake BOARD=emsk BD_VER=22 CUR_CORE=arcem7d TOOLCHAIN=mw JTAG=usb cfg
```

```bash
gmake BOARD=emsk BD_VER=22 CUR_CORE=arcem7d TOOLCHAIN=mw JTAG=usb opt
```

```bash
gmake BOARD=emsk BD_VER=22 CUR_CORE=arcem7d TOOLCHAIN=mw clean
```

```bash
gmake BOARD=emsk BD_VER=22 CUR_CORE=arcem7d TOOLCHAIN=mw boardclean
```

```bash
gmake BOARD=emsk BD_VER=22 CUR_CORE=arcem7d TOOLCHAIN=mw distclean
```

--------------------------------

### Compile, Link, Download, and Run Project (`make ... run`)

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/getting_started/makefile_manual

Compiles and links the project, then downloads and executes it on the target board. The example shows running on IoTDK with specific configurations, and a simplified version without default options.

```makefile
make BOARD=iotdk BD_VER=10 CUR_CORE=arcem9d TOOLCHAIN=mw JTAG=usb run
```

```makefile
make BOARD=iotdk TOOLCHAIN=mw JTAG=usb run
```

--------------------------------

### Create OS Makefile Template (FreeRTOS.mk Example)

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/developer/add_new_os

This snippet provides a template for creating a new OS-specific makefile, using 'FreeRTOS.mk' as an example. It outlines the commands needed to build the OS and generate a static library.

```makefile
# Example: FreeRTOS.mk

CPU_CORE := csky

ifeq ($(strip $(TARGET_CPU_CORE)), $(CPU_CORE))

	TARGET_LIB := libFreeRTOS.a

	CSRCS += FreeRTOS.c \
		     port.c \
		     list.c \
		     queue.c \
		     tasks.c \
		     timers.c

	INC_DIRS += FreeRTOS/Include

	ASMSRCS += portasm.S

	# Build FreeRTOS library
	$(OBJDIR)/%.o: %.c
		$(CC) $(CFLAGS) -I$(OBJDIR) -I$(OBJDIR)/FreeRTOS/Include -c $< -o $@

	$(OBJDIR)/%.o: %.S
		$(AS) $(ASFLAGS) -I$(OBJDIR) -I$(OBJDIR)/FreeRTOS/Include -c $< -o $@

	# Create static library
	$(TARGET_LIB): $(OBJS)
		$(AR) $(ARFLAGS) $@ $^

	# Build OS
	$(OBJDIR)/$(TARGET_LIB): $(TARGET_LIB)
		cp $< $@

else
	# Unsupported CPU Core
endif
```

--------------------------------

### Build Example Blinky for IoTDK

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/board/iotdk

Commands to build the example_blinky project for the IoTDK board using either the ARC GNU toolchain or the MWDT toolchain.

```makefile
cd embarc_osp\example\baremetal\blinky
# for ARC GNU toolchain
make TOOLCHAIN=gnu BOARD=iotdk
# for MWDT toolchain
make TOOLCHAIN=mw BOARD=iotdk

```

--------------------------------

### Run Example Blinky for IoTDK

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/board/iotdk

Commands to run the example_blinky project on the IoTDK board using either the ARC GNU toolchain or the MWDT toolchain.

```makefile
cd embarc_osp\example\baremetal\blinky
# for ARC GNU toolchain
make TOOLCHAIN=gnu BOARD=iotdk run
# for MWDT toolchain
make TOOLCHAIN=mw BOARD=iotdk run

```

--------------------------------

### Build and Run Examples with ARC GNU Toolchain

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/developer/application_development

These commands are used to build, run, debug, and manage build configurations for embARC OSP examples using the ARC GNU toolchain. They specify the board, board version, core, and toolchain.

```bash
make BOARD=emsk BD_VER=22 CUR_CORE=arcem7d TOOLCHAIN=gnu
```

```bash
make BOARD=emsk BD_VER=22 CUR_CORE=arcem7d TOOLCHAIN=gnu JTAG=usb run
```

```bash
make BOARD=emsk BD_VER=22 CUR_CORE=arcem7d TOOLCHAIN=gnu JTAG=usb gui
```

```bash
make BOARD=emsk BD_VER=22 CUR_CORE=arcem7d TOOLCHAIN=gnu JTAG=usb bin
```

```bash
make BOARD=emsk BD_VER=22 CUR_CORE=arcem7d TOOLCHAIN=gnu JTAG=usb cfg
```

```bash
make BOARD=emsk BD_VER=22 CUR_CORE=arcem7d TOOLCHAIN=gnu JTAG=usb opt
```

```bash
make BOARD=emsk BD_VER=22 CUR_CORE=arcem7d TOOLCHAIN=gnu clean
```

```bash
make BOARD=emsk BD_VER=22 CUR_CORE=arcem7d TOOLCHAIN=gnu boardclean
```

```bash
make BOARD=emsk BD_VER=22 CUR_CORE=arcem7d TOOLCHAIN=gnu distclean
```

--------------------------------

### Debug Example Blinky for IoTDK

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/board/iotdk

Commands to initiate debugging for the example_blinky project on the IoTDK board using either the ARC GNU toolchain or the MWDT toolchain.

```makefile
cd embarc_osp\example\baremetal\blinky
# for ARC GNU toolchain
make TOOLCHAIN=gnu BOARD=iotdk gui
# for MWDT toolchain
make TOOLCHAIN=mw BOARD=iotdk gui

```

--------------------------------

### WiFi Connection Status Messages

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/faq/faq

Displays example messages indicating the status of a WiFi connection for the embARC OSP. It shows both successful connection events and common failure messages, along with detailed lwIP example output.

```shell
WF_EVENT_CONNECTION_SUCCESSFUL.
When connecting fails, the message is WF_EVENT_CONNECTION_FAILED. The common message for lwIP examples is shown below.
Now trying to connect to WIFI Hotspot, Please wait about 30s!
MRF24G Device Information As Follows:
Device Type:2, ROM Ver:31, Patch Ver:7
Connection Profile ID:1
WF INIT SUCCESSFULL!
PMWIFI_0 MAC ADDRESS:00-1e-c0-0e-71-ac
WF_EVENT_CONNECTION_FAILED     --> sometimes happens
WF_EVENT_CONNECTION_SUCCESSFUL
Link is UP!
```

--------------------------------

### Clean and Build Project (`make ... build`)

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/getting_started/makefile_manual

Cleans previous build artifacts and then compiles and links the project with the specified parameters. An example shows building for EMSK with specific versions and toolchain.

```makefile
make BOARD=emsk BD_VER=11 CUR_CORE=arcem6 TOOLCHAIN=gnu build
```

--------------------------------

### Debug Project (`make ... gui`)

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/getting_started/makefile_manual

Compiles, links, and loads the project into a debugger for active debugging. The example demonstrates debugging on EMSK with specific versions, toolchain, and JTAG connection.

```makefile
make BOARD=emsk BD_VER=22 CUR_CORE=arcem9d TOOLCHAIN=mw JTAG=usb [your command]
```

--------------------------------

### Copyright Disclaimer Example

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/license/license

A sample copyright disclaimer for an employer or institution to sign, relinquishing copyright interest in a program written by an employee.

```text
Yoyodyne, Inc., hereby disclaims all copyright interest in the program Gnomovision' (which makes passes at compilers) written by James Hacker.
<signature of Ty Coon>, 1 April 1989
Ty Coon, President of Vice
```

--------------------------------

### Install MCUBoot Dependencies

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/lib/mcuboot

Installs necessary Python dependencies for MCUBoot using pip. This command should be run from the MCUBoot library directory within the embARC project.

```bash
cd <embarc_root>/library/mcuboot
pip3 install --user -r scripts/requirements.txt
```

--------------------------------

### IoTDK Serial Output Example

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/board/iotdk

This snippet shows the expected U-Boot output when the IoTDK board is reset, indicating successful initialization of the serial console.

```text
U-Boot 2018.03-rc3-00028-g161e5eeaa4a4-dirty (Mar 05 2018 - 12:56:14 +0300)

DRAM:  128 KiB
MMC:   Synopsys Mobile storage: 0
Loading Environment from FAT... Card did not respond to voltage select!
** Bad device mmc 0 **
Failed (-5)
In:    serial0@80014000
Out:   serial0@80014000
Err:   serial0@80014000
=>

```

--------------------------------

### Install Custom Exception Entry Point (C)

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/arc/arc

Allows definition of a custom entry point to replace the default behavior for CPU exceptions and interrupts. This function is used to install the desired handlers for specific exceptions or interrupts.

```c
#include "arc_exception.h"

// Install custom handler for CPU exceptions
void my_cpu_exception_handler(void) {
    // Handle CPU exception
}

void install_custom_handler() {
    exc_entry_install(EXC_CPU, my_cpu_exception_handler);
}

```

--------------------------------

### Check Sphinx Version

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/developer/documentation_generation

Verifies the installed version of Sphinx, a documentation generator used for Python projects. This command confirms if Sphinx is installed and accessible.

```bash
>sphinx-build --version
Sphinx (sphinx-build) 1.6.3
```

--------------------------------

### Link Extra Application Libraries (APPL_LIBS)

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/developer/build_system_documentation

Adds extra libraries to be linked with the application. For example, '-lm' links the math library, which is supported by the ARC GNU toolchain.

```makefile
APPL_LIBS = -lm
```

--------------------------------

### ARC Processor Startup Assembly

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/arc/arc

The processor-level startup routine for ARC processors, implemented in assembly. It handles initial hardware setup, C runtime initialization, and transitions to the board_main function. This file is crucial for the initial execution flow after reset.

```assembly
/* arc_startup.s
 * Processor level startup routines
 */

.section .text
.global _start

_start:
    /* Save current SP */
    mov     sp, r0

    /* Initialize stack pointer */
    lis     r1, _stack_end
    addi    r1, r1, _stack_end
    mov     sp, r1

    /* Call hardware_init_hook if defined */
#ifdef hardware_init_hook
    bl      hardware_init_hook
#endif

    /* Initialize memory controller if defined */
#ifdef memory_init_hook
    bl      memory_init_hook
#endif

    /* Copy data and BSS sections */
    /* ... (copy logic) ... */

    /* Call software_init_hook if defined */
#ifdef software_init_hook
    bl      software_init_hook
#endif

    /* Initialize exception handling */
    bl      arc_exc_init

    /* Jump to board_main */
    bl      board_main

    /* Infinite loop if board_main returns */
loop:
    j       loop

```

--------------------------------

### ARC EM Starter Kit Serial Output Example

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/board/emsk

This snippet shows the expected serial output from the ARC EM Starter Kit during self-test, including firmware and bootloader versions, core configuration, and test results.

```text
***********************************
**       Synopsys, Inc.          **
**     ARC EM Starter kit        **
**                               **
** Comprehensive software stacks **
**   available from embARC.org   **
**                               **
***********************************
Firmware   Feb 22 2017, v2.3
Bootloader Feb 22 2017, v1.1
ARC EM11D, core configuration #3

ARC IDENTITY = 0x43
RF_BUILD = 0xc902
TIMER_BUILD = 0x10304
ICCM_BUILD = 0x804
DCCM_BUILD = 0x10804
I_CACHE_BUILD = 0x135104
D_CACHE_BUILD = 0x215104

SelfTest PASSED

Info: No boot image found

```

--------------------------------

### Set Core Configuration using Make Command

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/developer/build_system_documentation

This command specifies the core configuration for the selected board version. For example, `make BOARD=emsk BD_VER=23 CUR_CORE=arcem11d` selects the arcem11d core for EMSK 2.3.

```makefile
make BOARD=emsk BD_VER=23 CUR_CORE=arcem11d
```

--------------------------------

### Build with Custom TCF File

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/developer/build_system_documentation

Demonstrates how to build a project using a custom tool configuration file (TCF). This is useful for specifying target board and core configurations. The example shows passing the TCF file name as an argument to the gmake command.

```makefile
gmake BD_VER=23 CUR_CORE=arcem7d TCF=arcem.tcf
```

--------------------------------

### Doxygen Example for C Code Documentation

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/contribute/CONTRIBUTING

This snippet demonstrates the use of Doxygen for documenting C source code, including parameter descriptions, return values, and brief explanations of functions. It follows common documentation best practices.

```c
/**
 * @brief       Reserve a DMA channel, and bind it with dma_chn, and set the dma
 *              trigger source
 *
 * @param[in]   channel                This can be DMA_CHN_ANY or any valid
 *                                     channel id. For DMA_CHN_ANY, it will try
 *                                     to peek an available channel. For any
 *                                     valid channel id, it will try to reserve
 *                                     that channel.
 * @param       dma_chn                uDMA channel structure, should not be
 *                                     NULL
 * @param[in]   source                 DMA trigger source, this can be any value
 *                                     in dma_request_source_t enum
 *
 * @retval      DMA_CHN_INVALID        dma_chn is NULL, or channel is not a
 *                                     valid one, or there is no channel
 *                                     available now
 * @retval      0-DMA_ALL_CHANNEL_NUM  the channel id that reserved
 */


```

--------------------------------

### Add Wi-Fi and Audio Drivers to Makefile

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/board/emsdp

This example shows how to include both a Wi-Fi rs9113 driver and an audio codec driver (max9880a) in the Makefile for a dual-functionality application.

```makefile
EXT_DEV_LIST += wifi/rs9113 audio/max9880a
```

--------------------------------

### Define Application Name and Source Directories

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/developer/build_system_documentation

This section covers setting application-specific variables like APPL (application name), APPL_CSRC_DIR (C source directories), APPL_ASMSRC_DIR (assembly source directories), and APPL_INC_DIR (include directories). These variables guide the build system to find and compile the application's code.

```makefile
# Define the application name
APPL := my_application

# Specify directories for C source files (separated by whitespace)
APPL_CSRC_DIR := src/app src/drivers

# Specify directories for assembly source files (if any)
APPL_ASMSRC_DIR := asm/startup

# Specify directories for include files (separated by whitespace)
APPL_INC_DIR := include/custom inc/hal
```

--------------------------------

### Board Initialization Steps in `board_init`

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/board/board

Defines the sequence of operations performed during board initialization within the embARC OSP framework. This includes installing device drivers, managing interrupts, setting up timers, and initializing peripherals and other board resources.

```c
/* Board initialization steps - defined in `board_init` function. */
/* Install required device driver objects, such as UART/SPI/IIC device objects. */
/* Clear and disable all interrupts. */
/* Initialize 1 ms timer interrupt. */
/* Initialize some peripherals if used. */
/* Initialize other required board resources such as mux controller. */
```

--------------------------------

### Example Container Call

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/lib/secureshield

Demonstrates how to call a registered container interface (`tst_func2`) from another container. The call passes arguments and expects a return value.

```c
ret = container_call(container1, tst_func2, 1, 2);
```

--------------------------------

### Check Doxygen Version

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/developer/documentation_generation

Checks the installed version of Doxygen, a tool used for generating documentation from annotated source code. This command ensures Doxygen is ready for use.

```bash
>doxygen --version
1.8.13
```

--------------------------------

### Build System Update: Object Folder Change

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/changelog/release_2015

This snippet shows the change in the example build object folder from `_obj_tool_core_` to `_obj_board_bd_ver/tool_core_` in the embARC build system.

```makefile
Change the example build object folder from _obj_tool_core_ to _obj_board_bd_ver/tool_core_
```

--------------------------------

### Example Access Control Table Initialization

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/lib/secureshield

Demonstrates the initialization of a static access control table (g_container_act) for a container, specifying various system resources like peripherals, memory, interrupts, and interfaces with their respective access attributes.

```c
static CONTAINER_AC_TABLE g_container_act[] = {
    /* memory mapper peripheral, {start_address, size in bytes, type | access} */
    {(void *)(PERIPHERAL_ADDR_BASE + REL_REGBASE_PINMUX), 0x1000, SECURESHIELD_ACDEF_UPERIPH},
    /* memory, {start_address, size in bytes, type | access} */
    {(void *)0x10000, 0x1000, SECURESHIELD_ACDEF_URAM},
    /* system resources-interrupt, {interrupt handler, interrupt no, type} */
    {default_interrupt_handler, INTNO_GPIO, SECURESHIELD_AC_IRQ},
    /* system resources-auxiliary registers, {start_address, size, type}*/
    {(void *)0x21, 0x3, SECURESHIELD_AC_AUX},
    /* container interface, {interface handler, number of interface handler arguments, type} */
{tst_func4, 4, SECURESHIELD_AC_INTERFACE},
};

```

--------------------------------

### Add Wi-Fi Driver to Makefile

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/board/emsdp

This example demonstrates how to add a Wi-Fi rs9113 driver to the Makefile for an embARC OSP project, enabling Wi-Fi functionality.

```makefile
EXT_DEV_LIST += wifi/rs9113
```

--------------------------------

### embARC HAL Example with Doxygen Comments

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/developer/coding_style

This C code snippet demonstrates the basic structure of an embARC application, including the inclusion of HAL and debug headers. It features a Doxygen-style comment for the main entry point and uses EMBARC_PRINTF for output.

```c
/* 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;
}
/** @} */

```

--------------------------------

### Select Toolchain using Make Command

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/developer/build_system_documentation

This option determines the toolchain used for compiling embARC applications. For example, `make BOARD=emsk BD_VER=23 CUR_CORE=arcem11d TOOLCHAIN=gnu` uses the ARC GNU toolchain.

```makefile
make BOARD=emsk BD_VER=23 CUR_CORE=arcem11d TOOLCHAIN=gnu
```

--------------------------------

### EmbARC Makefile Build Targets

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/getting_started/makefile_manual

These are the primary targets for building and generating output files. They cover options like building all examples, generating binary files, creating Intel Hex files, cleaning and compiling, generating dump information, disassembling object files, and displaying size information.

```makefile
make all

```

```makefile
make bin

```

```makefile
make hex

```

```makefile
make build

```

```makefile
make dump

```

```makefile
make dasm

```

```makefile
make size

```

```makefile
make sign

```

--------------------------------

### Middleware Makefile Structure

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/developer/add_new_middleware

This example demonstrates the basic structure of a middleware makefile, including definitions for include directories, source files (C and Assembly), and preprocessor defines. It serves as a template for adding new middleware packages.

```makefile
# Example Makefile Structure for a Middleware Package

# Include directories for the middleware
MID_INCDIR += -I${CURDIR}/inc

# Source files (C)
MID_XXX_CSRCS += src/example.c

# Source files (Assembly)
MID_XXX_ASMSRCS += src/example.s

# Preprocessor defines
MID_DEFINES += EXAMPLE_FEATURE_ENABLED

```

--------------------------------

### mbed TLS Patch Application Output

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/middleware/iot/mbedtls

This is an example output from the mbed TLS patch application script. It shows the process of cloning the mbedtls repository, checking out a specific version, and applying the embARC support patch. It also highlights potential whitespace issues in the patch file.

```shell
$ cd <embARC>/middleware/mbedtls
$ bash ./apply_embarc_patch.sh
  Clone repo from https://github.com/ARMmbed/mbedtls.git at commit or tag mbedtls-2.4.1
  Branch master set up to track remote branch coverity_scan from origin.
  Already on 'master'
  commit b2c6b254430bd97aced22a4946bec1a51ccd5173
  Author: Janos Follath <janos.follath@arm.com>
  Date:   Tue Dec 13 14:14:03 2016 +0000

  Update library version number to 2.4.1
  Switched to a new branch 'embARC'
  Try to apply patch for this repo
  Applying: Add embARC (FreeRTOS+LwIP) support to mbedtls
  .git/rebase-apply/patch:433: space before tab in indent.
           (void) mbedtls_timing_get_timer( &ctx->timer, 1 );
  .git/rebase-apply/patch:448: space before tab in indent.
           return( 2 );
  .git/rebase-apply/patch:451: space before tab in indent.
           return( 1 );
  .git/rebase-apply/patch:458: new blank line at EOF.
  +
  warning: 4 lines add whitespace errors.
  Patches are applied


```

--------------------------------

### Set Target Board using Make Command

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/developer/build_system_documentation

This command allows you to specify the target hardware board for the embARC OSP build. The default board is 'emsk'. For example, `make BOARD=emsk` selects the EMSK board.

```makefile
make BOARD=emsk
```

--------------------------------

### Generate Application Binary with ARC GNU Toolchain

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/faq/faq

This command generates a binary file for applications on EMSK boards using the ARC GNU toolchain. The generated file should be renamed to '_boot.bin' and copied to an SD card for use with a secondary bootloader.

```bash
make TOOLCHAIN=gnu BD_VER=22 CUR_CORE=arcem7d bin
```

--------------------------------

### Clone embARC OSP Repository and Checkout Release

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/changelog/changelog

This snippet demonstrates how to clone the embARC OSP GitHub repository and checkout a specific release tag using Git commands. It requires Git to be installed and accessible in the terminal.

```git
git clone https://github.com/foss-for-synopsys-dwc-arc-processors/embarc_osp.git embarc_osp
cd embarc_osp
git checkout tags/2017.12
```

--------------------------------

### Run example_blinky on ARC EM Starter Kit

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/board/emsk

Runs the 'example_blinky' project on the ARC EM Starter Kit after building. It uses the same toolchain, board, and core configuration as the build step.

```makefile
cd embarc_osp\example\baremetal\blinky
# for ARC GNU toolchain
make TOOLCHAIN=gnu  BOARD=emsk BD_VER=22 CUR_CORE=arcem7d run
# for MWDT toolchain
make TOOLCHAIN=mw  BOARD=emsk BD_VER=22 CUR_CORE=arcem7d run
```

--------------------------------

### Linker Script Section Generation for Container Data

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/lib/secureshield

Example snippet showing the generation of a linker script section for the data of 'container1' in a SecureShield application. This defines the start of the data section.

```linker_script
.container1.ram.data ALIGN(32) : {
 _f_data_container1 = .;
```

--------------------------------

### Set JTAG Frequency with ARC GNU Toolchain (EMSK 1.x)

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/faq/faq

This snippet shows how to modify the OpenOCD configuration file for EMSK 1.x to set the JTAG frequency. The 'adapter_khz' value should be changed to match the target CPU frequency in KHz. '<ARC_GNU>' represents the installation directory of the ARC GNU toolchain.

```openocd
adapter_khz=<CPU_FREQUENCY_IN_KHZ>

```

--------------------------------

### Build example_blinky for ARC EM Starter Kit

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/board/emsk

Builds the 'example_blinky' project for the ARC EM Starter Kit using either the GNU or MWDT toolchain. It specifies the board, board version, and core configuration.

```makefile
cd embarc_osp\example\baremetal\blinky
# for ARC GNU toolchain
make TOOLCHAIN=gnu BOARD=emsk BD_VER=22 CUR_CORE=arcem7d
# for MWDT toolchain
make TOOLCHAIN=mw  BOARD=emsk BD_VER=22 CUR_CORE=arcem7d
```

--------------------------------

### ARC HSDK Debug Output Example

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/board/hsdk

Example of the expected output from the ARC HSDK upon reset, showing bootloader information and hardware revision. This output is typically viewed using a serial terminal emulator.

```text
********************************
**       Synopsys, Inc.       **
**   ARC HS Development Kit   **
********************************
** IC revision: Rev 1.0
Bootloader revision: Jun 12 2016, 08:54:06
Bootloader location: 0x1 (internal ROM)
Bootloader aux: 0x9 (sg15E,4Gb,x8,2r)
Bootloader speedmode: Slow
Bootloader multicore: 0x0 (Single-core)


```

--------------------------------

### Select Libraries (LIB_SEL)

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/developer/build_system_documentation

Chooses system libraries for the embARC application. 'clib' provides C Library support, and 'secureshield' is for SecureShield Library.

```makefile
LIB_SEL=clib
```

```makefile
LIB_SEL=secureshield
```

--------------------------------

### Generate Board Configuration Files (Windows/Linux)

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/bsp/bsp_build_cmd

Commands to navigate to the configuration directory and generate board configuration files using 'tcftool' for MetaWare and ARC GNU toolchains. This prepares the environment for building.

```bash
# EMSK 2.3, ARC EM7D on Windows
cd embarc_bsp\board\emsk\configs\23
# EMSK 2.3, ARC EM7D on Linux
cd embarc_bsp/board/emsk/configs/23
# MetaWare
tcftool arcem7d.tcf -q -x C_defines,arc_core_config.h -x ccac.arg
# ARC GNU
tcftool arcem7d.tcf -q -x C_defines,arc_core_config.h -x gcc.arg
```

--------------------------------

### Control Board Initialization Process (USE_BOARD_MAIN)

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/developer/build_system_documentation

Manages which board initialization process is used. Setting USE_BOARD_MAIN to 0 uses the standard board init process compatible with older embARC releases, requiring manual board_init.

```makefile
USE_BOARD_MAIN=0
```

```makefile
USE_BOARD_MAIN=1
```

--------------------------------

### Debug example_blinky on ARC EM Starter Kit

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/board/emsk

Initiates debugging for the 'example_blinky' project on the ARC EM Starter Kit. It supports both GNU and MWDT toolchains and requires specifying the board, version, and core.

```makefile
cd embarc_osp\example\baremetal\blinky
# for ARC GNU toolchain
make TOOLCHAIN=gnu  BOARD=emsk BD_VER=22 CUR_CORE=arcem7d gui
# for MWDT toolchain
make TOOLCHAIN=mw  BOARD=emsk BD_VER=22 CUR_CORE=arcem7d gui
```

--------------------------------

### SPI Info Macros (C)

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/device/spi

Macros for setting and getting extra information associated with the SPI info structure.

```c
#define DEV_SPI_INFO_SET_EXTRA_OBJECT(_spi_info_ptr_ , _extra_info_)
#define DEV_SPI_INFO_GET_EXTRA_OBJECT(_spi_info_ptr_)
```

--------------------------------

### Access Control Table Example

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/lib/secureshield

Illustrates the definition of an access control table, specifying various system resources and their access rights for a container.

```APIDOC
## Access Control Table Example

### Description
An example demonstrating how to populate an access control table (`CONTAINER_AC_TABLE`) to grant a container specific access to system resources like peripherals, memory, interrupts, and auxiliary registers.

### Example Definition
```c
static CONTAINER_AC_TABLE g_container_act[] =
{
    /* memory mapper peripheral, {start_address, size in bytes, type | access} */
    {(void *)(PERIPHERAL_ADDR_BASE + REL_REGBASE_PINMUX), 0x1000, SECURESHIELD_ACDEF_UPERIPH},
    /* memory, {start_address, size in bytes, type | access} */
    {(void *)0x10000, 0x1000, SECURESHIELD_ACDEF_URAM},
    /* system resources-interrupt, {interrupt handler, interrupt no, type} */
    {default_interrupt_handler, INTNO_GPIO, SECURESHIELD_AC_IRQ},
    /* system resources-auxiliary registers, {start_address, size, type}*/
    {(void *)0x21, 0x3, SECURESHIELD_AC_AUX},
    /* container interface, {interface handler, number of interface handler arguments, type} */
    {tst_func4, 4, SECURESHIELD_AC_INTERFACE},
};
```

### Resource Types and Attributes

**Container Resource Type:**
- **SECURESHIELD_AC_MEMORY**: Allocate a memory region (start_address, size).
- **SECURESHIELD_AC_PERIPHERAL**: Allocate a memory-mapped peripheral area (start_address, size).
- **SECURESHIELD_AC_IRQ**: Allocate an interrupt (interrupt_handler, interrupt_no).
- **SECURESHIELD_AC_AUX**: Allocate an auxiliary address space (aux_start_address, size).

**Container Resource Attribute:**
- **SECURESHIELD_AC_UEXECUTE**: Execution with user privilege.
- **SECURESHIELD_AC_UWRITE**: Write with user privilege.
- **SECURESHIELD_AC_UREAD**: Read with user privilege.
- **SECURESHIELD_AC_KEXECUTE**: Execution with kernel privilege.
- **SECURESHIELD_AC_KWRITE**: Write with kernel privilege.
- **SECURESHIELD_AC_KREAD**: Read with kernel privilege.
- **SECURESHIELD_AC_SIZE_ROUND_UP**: The resource size should be rounded up.
- **SECURESHIELD_AC_SIZE_ROUND_DOWN**: The resource size should be rounded down.
- **SECURESHIELD_AC_SHARED**: The resource is a shared resource (no implementation now).
- **SECURESHIELD_AC_SECURE**: The resource is a secure resource.
- **SECURESHIELD_AC_NORMAL**: The resource is a normal resource.
```

--------------------------------

### Select Operating System (OS_SEL)

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/developer/build_system_documentation

Chooses the operating system for the embARC application. Options include 'freertos' for FreeRTOS. Leaving OS_SEL blank uses a bare-metal runtime.

```makefile
OS_SEL=freertos
```

```makefile
OS_SEL=
```

--------------------------------

### Running make help command

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/getting_started/makefile_manual

This command displays help information and a list of available build targets, clean targets, debug/run targets, and configuration options for the embARC make system. It is useful for understanding and utilizing the makefile functionalities.

```makefile
make help
```

```makefile
gmake help
```

--------------------------------

### Check Current Configuration (`make cfg`)

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/getting_started/makefile_manual

Displays the current build settings and lists supported configurations for boards, core configurations, toolchains, and JTAG connections. This is useful for understanding the build environment.

```makefile
make cfg
```

--------------------------------

### Building ARC Projects with HSDK

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/board/hsdk

Commands to build the example_blinky project for the ARC HSDK using either the GNU or MWDT toolchains. Navigates to the project directory and invokes the make command with specific toolchain and board configurations.

```bash
cd embarc_osp\example\baremetal\blinky
# for ARC GNU toolchain
make TOOLCHAIN=gnu BOARD=hsdk
# for MWDT toolchain
make TOOLCHAIN=mw BOARD=hsdk

```

--------------------------------

### Move Linker Scripts and Configuration Files (Windows/Linux)

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/bsp/bsp_build_cmd

Instructions for moving linker scripts and configuration files to the application folder for both MetaWare and ARC GNU toolchains on Windows and Linux. This step is crucial for the build process.

```bash
# MetaWare on Windows
mv arc_core_config.h ccac.arg ../../../../example/hello/mwdt
cp ld\linker_mw.ld ../../../../example/hello/mwdt
cd ..\..\..\..\example\hello\mwdt
mv linker_mw.ld arc_core.ld
# ARC GNU on Windows
mv arc_core_config.h gcc.arg ../../../../example/hello/arcgnu
cp ld\linker_gnu.ld ../../../../example/hello/arcgnu
cd ..\..\..\..\example\hello\arcgnu
mv linker_gnu.ld arc_core.ld
# MetaWare on Linux
mv arc_core_config.h ccac.arg ../../../../example/hello/mwdt
cp ld/linker_mw.ld ../../../../example/hello/mwdt
cd ../../../../example/hello/mwdt
mv linker_mw.ld arc_core.ld
# ARC GNU on Linux
mv arc_core_config.h gcc.arg ../../../../example/hello/arcgnu
cp ld/linker_gnu.ld ../../../../example/hello/arcgnu
cd ../../../../example/hello/arcgnu
mv linker_gnu.ld arc_core.ld
```

--------------------------------

### Define OS HAL Header in os_hal_inc.h

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/developer/add_new_os

This snippet shows how to define necessary configurations in 'os_hal_inc.h' for a new OS. It includes specifying the header file path for the target OS and defining the 'os_hal_exc_init' function for exception and interrupt initialization.

```c
#include "<target-os>/inc/os_hal.h"

#define OS_HAL_EXC_INIT()  os_hal_exc_init()

void os_hal_exc_init(void);

#ifdef OS_HAL_INT_NUM
#define OS_HAL_INT_NUM  OS_HAL_INT_NUM
#endif
```

--------------------------------

### Specify Digilent USB JTAG Name

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/developer/build_system_documentation

This option allows you to specify the Digilent USB JTAG name. The default value is empty. This is useful for debugging specific hardware setups.

```makefile
make DIG_NAME=YourJtagName
```

--------------------------------

### Execute Command with Specific Configurations

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/getting_started/makefile_manual

Allows execution of a command with custom build parameters such as board, core configuration, toolchain, and JTAG connection. This enables targeted builds and debugging sessions.

```makefile
make BOARD=emsk CUR_CORE=arcem7d TOOLCHAIN=gnu JTAG=usb [your command]
```

--------------------------------

### ARC Board Level Startup and Initialization (C)

Source: https://foss-for-synopsys-dwc-arc-processors.github.io/embarc_osp/doc/build/html/arc/arc

The board-level startup function in C, responsible for initializing hardware, middleware, and the OS. It sets up peripherals, enables console output via xprintf, and manages middleware like FatFs and NT-Shell. It also handles OS task creation if enabled.

```c
/* board.c
 * Board level startup and initialization
 */

#include "embarc.h"
#include "xprintf.h"

#ifdef MID_FATFS
#include "diskio.h"
#include "ff.h"
#endif

#ifdef MID_NTSHELL
#include "nts.h"
#endif

#ifdef ENABLE_OS
#include "os.h"
#endif

/* Function prototypes */
void board_init(void);

void board_main(void) {
    /* Board-level hardware initialization */
    board_init();

    /* Initialize xprintf for console output */
xprintf_init();
    xprintf("embARC OSP board init\n");

#ifdef MID_FATFS
    /* Initialize FatFs and mount SD card */
    if (fdisk_ins") == 0) {
        if (f_mount(0, "0:") == FR_OK) {
            xprintf("SD card mounted\n");
        } else {
            xprintf("SD card mount failed\n");
        }
    } else {
        xprintf("SD card not present\n");
    }
#endif

#ifdef MID_NTSHELL
    /* Initialize NT-Shell */
    nts_init();
    xprintf("NT-Shell initialized\n");
#endif

#ifdef ENABLE_OS
    /* OS specific initialization */
    os_init();

    /* Create main task for user main function */
    os_task_create(NULL, "main_task", main, OS_PRIORITY_NORMAL, OS_STACK_SIZE, NULL);

#ifdef MID_LWIP
    /* Create WiFi task if LWIP is enabled and WiFi is used */
    // ... WiFi task creation logic ...
#endif

    /* Start the OS scheduler */
os_start();
#else
    /* If no OS, call main directly */
    main();
#endif
}

void board_init(void) {
    /* User-defined board-specific hardware initialization */
    /* Initialize clocks, PLLs, peripherals etc. */
    /* Example: GPIO initialization */
    // gpio_init();
}

```
Tokens:
Raw