Port Projects from IAR Embedded Workbench to Embedded Studio

From SEGGER Wiki
Revision as of 13:05, 12 January 2021 by Nino (talk | contribs) (Troubleshooting)
Jump to: navigation, search

This Wiki article describes how to import IAR EWARM projects into SEGGER Embedded Studio using the build in project importer. With the project importer you can either keep using the IAR tool chain inside Embedded Studio or
use the SEGGER tool chain that is used inside Embedded Studio. By switching your project to Embedded Studio you can directly benefit from features like multi-threaded compiling, fast and simple project search, indexing and more.
Many features are even available should you still decide to be using the IAR tool chain inside Embedded Studio. A full feature list can be found here.

Setup

The following import tutorial will be based on the following Hardware and Software combinations:

  • SEGGER Embedded Studio 5.32a 64-bit (Project importer works on 3.10 or later)
  • IAR EWARM 8.50
  • Target Evalboard: SEGGER emPower

The following file contains the example project for you to try out:

IAR_to_ES_Tutorial.zip

Import tutorial

  • Open your copy of Embedded Studio and go to File -> Import IAR EWARM / Keil MDK Project... then navigate to the project file you want to import and select it.
IAR Example Project Folder
  • Now you will have the opportunity to choose between:
    • External Toolchain: imports the project and configures it to be built with the original toolchain.
    • Internal Toolchain: imports the project and sets the configuration for the Embedded Studio tool chain.
    • Internal and External Toolchains: creates a set of build configurations to build with the original tool chain and one set to build with the Embedded Studio tool chain.
    • "IAR Installation Directory" where you get the option to use a different external IAR compiler if you have multiple IAR EWARM versions installed.
  • To migrate to Embedded Studio it is recommended to create build configurations for internal and external tool chains so you can easily switch between the tool chains later on.
Project importer options
  • If everything worked out well the following status window should pop up:
Successful import
  • Embedded Studio will automatically create build configurations for debug and release versions with the internal and external compiler that have been present in the existing IAR project.
  • To switch between them the drop down menu in the "Project Explorer" can be used.
Build configurations window
  • To debug the example project with the IAR compiler choose "Debug_External" in the drop down menu and build the project by pressing F7.
  • For most projects this will work out of the box, if it does not build out of the box please refer to section "Troubleshooting".

Note:While it is possible to only run the external configuration where the external tool chain is called, we recommend to switch to the internal SEGGER tool chain as some e.g. debug features are not fully available when debugging code created with external tool chains.

How to switch to internal Embedded Studio compiler

  • To use the full potential of Embedded Studio it is required to use the internal SEGGER compiler which is based on Clang.
  • This can be done in the provided example project by simply going to the drop down menu and select "Debug_Internal".
  • The project will now be built when pressing F7 with the internal SEGGER compiler by default. Other internal compilers (gcc/clang) can be enabled in the project options instead.
  • After a successful build with the internal compiler Embedded Studio will automatically calculate how much flash and RAM will be occupied on your target device and represent it visually in the output window.
Code flash and RAM usage
  • Note: this feature is only available when using the internal compilers.
  • For most projects switching to the internal compiler work out of the box, if it does not build out of the box please refer to section "Troubleshooting".

If you plan on using the internal SEGGER tool chain anyhow we recommend to skip the import tool and create a new project with the project wizard and if available with a CPU support package. This way all Embedded Studio specific and target specifc project settings are already in place. All that is needed to do now is to add the sources from your IAR project to your Embedded Studio folder and fix IAR specific compile errors and eventually the linker script and memory map setup as described in troubleshooting. On average this approach is less time consuming.

Troubleshooting

While imported projects will usually re-build with the external tool chain out-of-the-box, for the internal SEGGER tool chian based project build configurations, some manual changes may be required.

In some cases the sources are created to be clang compatible, then you can seamlessly switch between original tool chain and SEGGER tool chain. When the original project is created from a software pack or SDK, it might already come with SEGGER tool chain compatible source files which can replace the former tool chain compatible files.

The following points list the most common changes which are required to migrate a project to Embedded Studio.

Internal Configuration

Memory Linker Script

The Embedded Studio project importer does not import linker scripts (e.g. IAR icf files). It sets up the basic memory map for the selected target device, which will put code into the internal flash and data into the internal SRAM.

For more advanced or different configurations, the memory map file and the section placement file have to be set up accordingly.

To place memory segments there are two options available in Embedded Studio:

  1. Place segments directly via project options under "Linker -> Section Placement Segments"
  2. Create a memory map .xml file or edit the default file provided by Embedded Studio and set it in project options under "Linker -> Use Manual Linker Script"

For example, a memory-map file representing a device with two memory segments called FLASH and SRAM could look something like this in the memory-map editor.

<Root name="Device1">
  <MemorySegment name="FLASH" start="0x10000000" size="0x10000" />
  <MemorySegment name="SRAM"  start="0x20000000" size="0x1000" />
</Root>

A corresponding section-placement file will refer to the memory segments of the memory-map file and will list the sections to be placed in those segments. This is done by using a memory-segment name in the section-placement file that matches the corresponding memory-segment name in the memory-map file.

For example, a section-placement file that places a section called .stack in the SRAM segment and the .vectors and .text sections in the FLASH segment would look like this:

<Root name="Flash Section Placement">
  <MemorySegment name="FLASH" >
    <ProgramSection name=".vectors" load="Yes" />
    <ProgramSection name=".text" load="Yes" />
  </MemorySegment>
  <MemorySegment name="SRAM" >
   <ProgramSection name=".stack" load="No" />
  </MemorySegment>
</Root>

To add new segments or sections simply edit the default file linked by Embedded Studio. The linked file can be found in the project options under "Linker -> Section Placement File".

More information about how to setup such files can be found in the Embedded Studio Help window in chapter "Linking and section placement".

Third Party Software and Libraries

Third party software, especially libraries, might be configured for one tool chain and do not compile with other tool chains.

Check if there is a port of the software for Embedded Studio / GCC or configure and rebuild the software for Embedded Studio / GCC.

Although libraries built for another tool chain may link with Embedded Studio, always take care and check that interfacing with the library works as expected.

Assembly Code

The syntax of assembler code and control commands in assembler files can be different across tool chains.

Although the resulting assembled instructions are identical, the assembler code to be written can be different across tool chains, for example numerical constants need to be declared differently for IAR and GCC/Clang.

Control commands which help writing assembler code is different, too. The syntax for symbols, labels, function definitions, and alike needs to be adjusted to work with the GNU assembler.

The following table shows some "popular" assembler directives that can be substituted by the corresponding conjugate:

IAR assembler directive GCC/Clang assembler directive
PUBLIC .global
SECTION .section
MACRO .macro
ENDM .endm
THUMB .thumb_func
END .end
EXTERN .extern
DC32 .word

For a complete list please refer to the corresponding assembler reference manuals.

Preprocessor Defines

Tool chains use different built-in definitions to identify the compiler which is used and to allow conditional compilation based on the configuration of core, device, endianess, and other settings.

It is mandatory to choose the correct definitions and recommended to make sure the code throws a warning or error when required definitions are not defined.

IAR defines __ICCARM__ and __IAR_SYSTEMS_ICC__ which can be used for identification, Embedded Studio defines __SES_ARM and __GNUC__.

For the target device IAR defines __ARM7M__ and __CORE__=__ARM7M__ when compiling for Cortex-M4, Embedded Studio uses __ARM_ARCH_7M__ instead.

Tool Chain Intrinsics

Compiler-specific functions like __disable_interrupt() or __no_operation() might not be available in Embedded Studio. Write corresponding replacement functions or avoid using them at all.

A replacement function for __no_operation() could look like this for GCC/Clang:

#define NO_OPERATION() __asm volatile ("nop")

To make it backwards compatible with IAR such a redefinition can be nested within preprocessor defines; __ICCARM__ for IAR EWARM and __SES_ARM for Embedded Studio.

Project Settings

Most project settings are set automatically by the project importer for the external and internal build configuration. In some more complex projects certain project settings need to be added manually.

For example by default no files are excluded from the internal build configuration, so if there is a compiler incompatible file the compiler will try to compile it and show errors (e.g. GCC/Clang incompatible assembler files).

To do this right click your project in the project explorer and select "Edit options". More information about the individual settings can be found in the Embedded Studio user manual.

User Included Directories

Many more complex projects link their sources from multiple folders in different paths. Make sure all needed folders are included in the build configuration under "Preprocessor -> User Include Directories".

Pre/Post Build Commands

Embedded Studio offers the possibility to use pre/post build commands familiar to the ones in IAR EWARM. However the project importer does not import these as the syntax between IAR and Embedded studio differs.

Should you be using such commands in IAR make sure you mimic them in Embedded Studio in the internal and external build configurations accordingly .

To execute multiple commands at once the use of a batch script is possible.

For example to enable a post link batch script go into the project options for the intended build config, go to "User Build Step" and edit the entry "Post-Link Command".

Now enter the relative or absolute path of the bat file and the optional parameters: Path/Example.bat Param1 Param2 ...

External Configuration

As Embedded Studio simply calls the IAR toolchain via command line it is simply a matter of calling it the same way as EWARM does to make the external build work. The import tool will try to detect as many project settings as possible from the IAR project setup. However as the IAR IDE may change with each update, some options may not be detected correctly.

To correct this the easiest method is to export the build command line from IAR and match it with the setup in Embedded Studio as follows:

  • Open your IAR project in EWARM
  • In the Build window right click into it and select Filter Level: All
  • Rebuild project
  • Copy the build log into an editor
  • Now close EWARM and open Embedded Studio
  • Right click your project in project explorer and select Export Build
  • Now compare the build command line of EWARM and Embedded Studio, if you see options missing on the Embedded Studio side correct them via the Embedded Studio project options as explained below

Correcting the build configuration

To correct the differences between the IAR build command line and the Embedded Studio one simply open the project options in Embedded Studio. The command line calls that will have to be corrected in most cases is for the compiler(iccarm), assembler(iasmarm) and the linker(ilinkarm). You can either set the corresponding project optiosn which construct the command line yourself. Or directly go to the External Build options in project options and edit the command line directly.

Now if you successfully matched the build commands of EWARM and Embedded Studio, your application should build without errors just like it did in the native IAR setup.