View source for Migrating projects from Embedded Studio V4 to V5

With the update of Embedded Studio to version 5 you get access to the new SEGGER Compiler, SEGGER Run Time Library for even smaller and faster code and a updated SEGGER Linker.
So if you have an old project that was created with Embedded Studio V4 or older the following must be considered when migrating from V4 to V5.
Make sure all points are considered. All referenced files can be found in the Embedded Studio installation folder.

== New Startup File ==
Due to improvements on how the SEGGER toolchain handles the target startup code the Cortex_M_Startup.s and SEGGER_THUMB_Startup.s must be updated. You can find the latest version of this file in your Embedded Studio installation folder under /samples/Cortex_M_Startup.s and /samples/SEGGER_THUMB_Startup.s


'''Note:''' When setting up a RAM debug config with the sources provided via [https://www.segger.com/products/development-tools/embedded-studio/technology/cpu-support/ CPU support packages] please note that the preprocessor define for the VTOR config has changed to __VTOR_CONFIG.

'''Note:''' The preprocessor define MEMORY_INIT has changed to __MEMORY_INIT.

'''Note:''' Generally the initial stack pointer is not set as this is usually done by the hardware. But if you would like to set up a RAM debug project you can set it manually. For this simply edit the Startup.s file as explained in the sources comments. Additionally set the project option "Starting Stack Pointer Value" to __stack_end__ .

== New Run Time Lib ==
To use the new SEGGER run time library the following project option must be set: Code->Library->Run Time Library->SEGGER

If you are using RTT sources in your application, make sure the SEGGER_RTT_Syscalls_<ToolChain>.c file is removed.

Also make sure to set the correct I/O type for your project in project setting Library I/O.

== New Linker File ==
The new linker script can be found under /samples/SEGGER_Flash.icf if you are using a Flash based project or /samples/SEGGER_RAM.icf if RAM based.

The most important change is that the following two lines need to be added to the initialization block:

<source lang=C>
initialize by symbol __SEGGER_init_heap     { block heap  };                                        // Init the heap if there is one
initialize by symbol __SEGGER_init_ctors    { block ctors };                                        // Call constructors for global objects which need to be constructed before reaching main (if any). Make sure this is done after setting up heap.
</source>

===Using GNU linker instead===
If you have an old project that still uses the GNU linker other steps are necessary.
As explained above the heap init must be done so functions like malloc can be used. For this simply update the files thumb_crt0.s or crt0.s, depending on the CPU architecture used in your project.
You can find both files under /source in the ES installation folder.

== Assembler Projects ==
When using an assembler project with the new linker script file make sure the following file is also included in your project /samples/SEGGER_crtinit.s

== Troubleshooting ==

=== Error: unsupported relocation on symbol ===

Raw error messages might be like:
  <inline asm>:1:2: error: unsupported relocation on symbol
          movs r1, $1
          ^

  SEGGER_RTT.c:730:3: error: unsupported relocation on symbol
  SEGGER_RTT_Conf.h:158:73: note: expanded from macro 'SEGGER_RTT_LOCK'
  <inline asm>:2:2: note: instantiated into assembly here
   PLEASE submit a bug report to https://bugs.llvm.org/ and include the crash backtrace, preprocessed source, and associated run script.
   Stack dump:
   0.	Program arguments: segger-cc -cc1 [...]
   1.	<eof> parser at end of file
   2.	Code generation

This error message is rather cryptic, but its reason and solution is as follows:

Some legacy code used '$' instead of '#' for immediate values in inline assembly.
While '$' is used in i386 asm, the arm assembly syntax only defines the use of '#'.
Older versions of GCC and clang supported both.
clang-11 and segger-cc 11 (as included in Embedded Studio V5.20) do not support the use of '$' anymore.

Source code which uses it must be updated to be compiled with Embedded Studio V5.