The MetaWare Development Toolkit

The well-known MetaWare Development Toolkit (MWDT) has expanded its supported cores to ensure the generation of highly efficient code for the new RISC-V ARC-V family of processors.

The MetaWare Development Toolkit includes a variety of tools that facilitate software development — LLVM-based compiler, linker, LLDB-based debugger (lldbac), processor simulator, and so on.

Getting the MetaWare Development Toolkit

The Synopsys Eval Portal (https://eval.synopsys.com/) allows you to request an evaluation license for Synopsys software products. MetaWare Development Toolkit is the one relevant for ARC-V processors. Follow these steps:

1. Log in to the portal (or register for an account).

2. Complete an Evaluation Request Form for your chosen software product(s).

3. Submit your shopping cart to complete your evaluation request. Receive email confirmation with a 30-day evaluation key.

4. Download the software and begin your evaluation.

5. Email-based support is available by writing to mwdt-eval-support@synopsys.com.

MetaWare Development Toolkit V-2024.03

New Features and Enhancements for RISC-V based ARC-V Processors

• Optimized performance on ARC-V targets.

• Added support for the RISC-V deviation specification (in particular, the long double type is 64 bits, not 128 bits).

• Added TCF support for ARC-V targets.

• Improved the performance of linker relaxation for ARC-V targets.

• Added the -Zicbop and -Zicboz options to enable the cache-block instructions for ARC-V targets.

• Added driver option -Hlibc=lib for ARC-V processors to select between the Picolib C runtime library (-Hlibc=pico) and the default MetaWare C runtime library (-Hlibc=mw). Note that this option also switches the default include paths. The current Picolib C version is 1.8.6.

• Added a run-lldbac debugger script for ARC-V targets so that you can run a GUI or command-line session using the same set of command-line options.

• Added more semihosting calls for ARC-V targets (note that the HEAPINFO and EXIT_EXTENDED semihosting calls are still not supported).

MetaWare Development Toolkit V-2023.12

The V-2023.12 version of the MetaWare Development Toolkit introduces experimental support for the ARC-V RMX processor series based on the RISC-V instruction-set architecture.

More information about this family can be found on the Synopsys website: Power-Efficient RISC-V Processors for Embedded Applications.

New Features and Enhancements

Support for RISC-V based ARC-V RMX Processors

• Experimental support is added for the RISC-V based ARC-V processors.

• Added support for the following RISC-V extensions: Zi, Zm, Za, Zc, Zba, Zbb, Zbc, Zbs, Zfinx, Zdinx, Zicsr, Zifencei, Zihintpause and Zicbom.

• Added support for the following code-size reduction extensions: Zca, Zcb, Zcf, Zcd and Zcmp.

• Added support for basic debugging in lldbac (command-line mode) and in Visual Studio Code (GUI mode).

Note

As this is the first release of the MetaWare Development Toolkit with ARC-V support, some functionality might have issues, some processor features might not yet be fully supported, and performance might be lower than expected performance of the final product.

Supported Platforms

Supported host operating systems and platforms limitations can be found in the MetaWare Release Notes document in /MetaWare/arc/docs/pdf.

Tools Limitations

Limitations of the experimental debugger support for ARC-V targets:

• The experimental debugger invoked with lldbac or lldbac-dap supports only ARC-V targets.

• Only the GDB RSP and RASCAL target connection protocols are supported. The MCD protocol is not supported. JTAG connections can only be established using an external GDB server.

• Only the following semihosting operations are supported: WRITE, READ, OPEN, CLOSE, ISTTY, FLEN, GETCMDLINE, EXIT.

• By default, the windows defined by the MetaWare debugger VS Code extension are not synchronized automatically with the selected stack frame. To enable stack-frame synchronization, add any expression to the Watch window in the Run and Debug tab and keep the Watch window open.

• Instruction (address) profiling is only supported in the GUI, not in command-line mode.

• The GUI does not open the Disassembly window automatically when debugger cannot find the source file. Open the Disassembly window manually in this case.

Basic Information

The MetaWare Development Toolkit supports building and debugging for ARC-V processors.

• IDE: The MetaWare IDE does not support ARC-V targets; instead, a VS Code plugin is provided as a .vsix file in the MetaWare/arc/lldbac folder. You must have an installed instance of VS Code from Microsoft to use this extension. The MetaWare Debugger User Guide in /MetaWare/arc/docs/pdf/arc-v has step-by-step instructions on how to install and configure this extension.

  The extension adds support for ARC-V debug sessions using the ARC-V MetaWare debugger. It supports basic debug operations such as running, halting, stepping, reading/writing registers, inspecting variables, setting breakpoints, and so on. The extension also includes some custom windows, for example an ARC-V Traps window and a Disassembly window.

• Compiler: The MetaWare ccac compiler driver supports building for ARC-V. ccac is an enhanced compiler driver tuned for maximum efficiency and providing smooth migration path for existing ARC users. See the MetaWare CCAC Programmer’s Guide for details. You can also build using the clangac driver, which is compatible with the LLVM default clang driver. This driver is the best choice for migrating existing code from non-ARC processors. See The First MetaWare Sample Application.

  • Assembler: The ccac and clangac drivers invoke an LLVM assembler behind the scenes. If you need to invoke the assembler directly, use llvm-asac. The MetaWare asac assembler does not support ARC-V.

  • Linker: The MetaWare linker supports linking for ARC-V using the ccac driver or using lldac directly. See the MetaWare ELF Linker and Utilities User’s Guide for details.

• Debugger: The MetaWare debugger supports ARC-V targets; see the dedicated documentation in /MetaWare/arc/docs/pdf/arc-v. The debugger uses the nSIM simulator, which supports ARC-V targets.

• Utilities: It is best to use the LLVM versions of ELF utilities provided in /bin for ARC-V builds. For example, it is better to use llvm-objdump instead of elfdump. The classic MetaWare elfdump is not updated to perform disassembly of ARC-V instructions. You can still use the classic MetaWare utilities, but some features (such as disassembly) are not available for ARC-V targets.

Known Issues and Limitations

Up-to-date lists of known and fixed issues are available online at https://www.synopsys.com/dw/doc.php/arc_tools/dw_arc_metaware/user_docs/mwdtkf/index.html.

Installation and Licensing

See the section on installation and licensing in the MetaWare Quick Start Guide.

The First MetaWare Sample Application

Building the Queens Example

A simple working Queens demo that shows how to compile, link, and execute a program for an ARC-V target is available in MetaWare/arc/examples/arcv_queens.

Prerequisite: Run setenv_mwdt.bat (.sh on Linux) in the top-level directory (ARC/ by default) to set the environment variables that describe where the MetaWare Development Toolkit and nSIM are installed.

Makefiles are provided for ccac and clangac.

Makefile

This makefile uses CCAC to compile and link the program. It is then run on nSIM directly (no debugger).

Makefile.clang

This makefile uses the Clang driver to compile and link the program and run it directly on nSIM (no debugger).

This method is a bit more complicated because you have to tell Clang where the C runtime is and how to use that runtime during compiling and linking.

Normally you place this information in a configuration file and then invoke Clang with that configuration file. For the steps to create and use a configuration file, see https://clang.llvm.org/docs/UsersManual.html#configuration-files

Use the following commands to clean and build the example:

% make clean              # clean the output files
% make a.out              # build executable a.out using ccac

% make -f Makefile.clang clean     # clean the output files
% make -f Makefile.clang a.out     # build executable a.out using clangac

This method uses the semihosting interface.

Alternative Compilation

% ccac -tcf=rmx100.tcf -O2 -g queens.c

This method uses the Hostlink interface, which is a MetaWare-specific host-access library. To use the standard RISC-V compatible semihosting interface, add -Hhostlib=semihost to the ccac options.

Running the Queens Example in nSIM

The tools for ARC-V include the nSIM simulator. You can invoke the standalone nSIM simulator for ARC-V using the nsimdrv driver or the runrv convenience script.

To execute the Queens demo on an ARC-V nSIM simulator, use the Makefile in MetaWare/arc/examples/arcv_queens.

% make run

The alternative way is to use the nsimdrv driver or runrv script directly from the console:

% nsimdrv -tcf ${METAWARE_ROOT}/arc/tcf/rmx100.tcf a.out     # Running the executable in nSIM using nsimdrv driver (Hostlink interface)
% runrv -p nsim_semihosting=1 -Za -Zm -Zbb a.out             # Running the executable in nSIM using runrv script (semihosting interface)

Be sure to launch the simulator with the same hosting interface as specified in the executable (Hostlink or semihosting). If the run is successful, the following message appears in the console.

go
    1   5   8   6   3   7   2   4

Debugging

Command-Line Interface

Launch the debugger:

% lldbac a.out

Launch the simulation from inside the debugger and connect to it:

> platform connect my_core nsim-gdb-properties="tcf=rmx100.tcf nsim_semihosting=1"

Omit nsim_semihosting=1 if your program was compiled with the Hostlink interface.

Start the executable:

> process launch -s

Break on main, _exit and Try:

> b main
> b _exit
> b Try

Skip the startup code:

> c

Now we are at main, continue:

> c

List local variables:

> var

Show backtrace:

> bt

Execute until next line:

> n
> n
> var

Evaluate an expression:

> p I+3
> c
> c
> var

Show and remove a breakpoint:

> break list
> break -d 3
> c

Print the list of functions sorted by how many times a profiling counter was incremented during function execution:

// Launch nSIM with instruction-counter support.
> platform connect my_core nsim-gdb-properties="tcf=rmx100.tcf icnts=1"
> process launch -s
// Print the list of available counters.
> display prof
// Print the list of functions sorted by the values of the "pc-frequency" counter.
> display prof pc-frequency
// For more information about the profiling command:
> display prof --help

Exit the debugger:

> q
[Y]

Installing the Visual Studio Code Extension

To run a GUI session, install and configure the VS Code extension using the following steps.

1. Install VS Code from the official site, https://code.visualstudio.com/download.

2. Open it and go to the Extensions tab.

3. Click the Ellipsis icon (…) in the top right corner of the Extensions tab and select Install from VSIX….

4. Go to location of the file from the installed MWDT package. Replace <METAWARE_ROOT> with actual MetaWare root:

   <METAWARE_ROOT>/arc/lldbac/synopsys-mdb-*.*.*.vsix, where *.*.* is a version, for example, it might be 2023.6.6.

5. Go to Settings > Extensions > MetaWare Debugger > Adapter Path and enter the path to this executable. Replace <METAWARE_ROOT> with the actual MetaWare root on your host:

   • On Windows: <METAWARE_ROOT>/arc/bin/lldbac-dap.exe

   • On Linux: <METAWARE_ROOT>/arc/bin/lldbac-dap

Debugging with Visual Studio Code

After installing the Visual Studio Code extension, execute the following steps to create a new launch configuration:

1. Open your workspace folder.

2. Go to Run and Debug tab.

3. Click on create a launch.json file and select MetaWare Debugger.

4. Click on Show all automatic debug configurations, select Add Configuration and select one of the MetaWare Debugger - * templates.

5. Enter details in all the highlighted fields.

6. Save the file.

Execute the following steps to run the new debug configuration:

1. Go to Run and Debug tab.

2. Select the configuration as per the requirement, in the dropdown menu.

3. Click the Start Debugging button near the dropdown menu.

Any errors in the debugger launch, are displayed in the bottom right part of VS Code GUI. See the MetaWare Debugger User Guide for more details.

After starting the debug session in VS Code, you can debug the application using a GUI interface. Below is a brief description of the main GUI debugger features.

Disassembly:

Go to ARC Displays and select the Disassembly window.

Breakpoints:

• In the Source window, double-click before the line number on a code line.

• In the Disassembly window, double-click before the instruction address on an instruction line.

• Go to Breakpoints to navigate and set properties of breakpoints.

Execution control:

Use the debugger control panel to run, stop, step and restart actions.

Show registers: - Go to ARC Displays > Registers and select the corresponding register panel (Debug Registers, Traps, Machine Counters, General Purpose Registers).

Show variables:

Go to Variables and select the corresponding panel (Locals, Globals).

Call stack:

Go to Call Stack and navigate using the functions.

Profiling:

To see the list of functions sorted by how many times a profiling counter was incremented during function execution:

1. Enable profiling in the simulator. For nSIM, add the icnts=1 property to the nsim-gdb-properties array in the debug session configuration.

2. Go to ARC Displays and open the Profiling window.

3. Select a profiling counter in the dropdown list and click the Load button.

To see how many times a profiling counter was incremented while executing the code at each address:

1. Enable profiling in the simulator. For nSIM, add the icnts=1 property to the nsim-gdb-properties array in the debug session configuration.

2. Go to ARC Displays and open the Disassembly View window.

3. Select a profiling counter in the rightmost dropdown list.

4. Check the column that appears to the right of the address column. Each entry in this column indicates how many times the counter was incremented while the counter was executing the instruction at the corresponding address.