Introduction
Up and including to version 2.0.0, the Kinetis Design Studio (KDS) is using a custom GNU toolchain built by SOMNIUM Technologies, referred here as 'legacy'. That toolchain is built from the Free Software Foundation (FSF) source base, with a few minor modifications. Starting with v3.0.0, KDS will use the unmodified GNU Tools for ARM Embedded (launchpad, GCC ARM Embedded in Launchpad) toolchain (4.8-2014-q3-update : Series 4.8 : GCC ARM Embedded release), referred here as 'launchpad'. Projects created with KDS v3.0.0 will use the 'launchpad' tools by default. The reasons for 4.8-2014-q3 instead of using the later 4.9 release is because of stability and smaller footprint of 4.8 applications.
Outline
This document outlines what are the differences between the 'legacy' and 'launchpad' toolchain, and what is needed to port existing 'legacy' projects to the 'launchpad' ones. It is already possible to use the 'launchpad' tools with KDS v2.0.0 today (see Switching ARM GNU Tool Chain and Libraries in Kinetis Design Studio | MCU on Eclipse), therefore the information in this document can be applied to KDS v2.0.0 to with using the 'launchpad' toolchain.
KDS Upgrade Assistant
Kinetis Design Studio V3.0.0 comes with a migration assistant to migrate projects to the GCC ARM Embedded (launchpad) tools. The migration assistant is accessible from the menu Project > KDS Upgrade Assistant:
This opens a dialog with the currently open projects in the workspace:
NOTE: if the Upgrade Assistant does not list your project, then you still can do the manual steps as listed below (changing the linker flags).
Select the project(s) you want to migrate and press Next.
In the next dialog you can configure the details of the conversion, then press Finish:
A report will be generated in each project directory:
Migration of KDS Projects
To migrate an existing 'legacy' project to a 'launchpad' project, usually only the linker settings need to be changed. For this go into the project properties, and check the 'Other linker flags' settings of the Linker. The table below shows the difference between the two:
| Legacy 'Other linker flags' | Launchpad 'Other linker flags' |
|---|---|
| <none> | -specs=nosys.specs |
| -nanolibc | -specs=nano.specs -specs=nosys.specs |
For example this project is a legacy project using the newlib-nano library:
To use it with the 'launchpad' toolchain, use
-specs=nano.specs -specs=nosys.specs
as shown below:
With this, normally projects are converted from the 'legacy' to the 'launchpad' toolchain.
NOTE: after switching toolchains, delete all intermediate or object files (e.g. delete the Debug/Output folder inside the project. Mixing object files or libraries from different toolchains and compilers will likely cause problems.
Now your project should compile fine. However, if you face a problem about wrong Thumb mode, see the following subsection.
Wrong or missing Thumb mode
If getting errors like
Error: selected processor does not support Thumb mode
error: interrupt Service Routines cannot be coded in Thumb mode
This means that the project settings do not properly pass the processor to the compiler. That problem mainly occurs with Kinetis SDK projects, and with Cortex-M0+ (Kinetis-L) projects.
As explained in the next section, the launchpad tools by default use the ARM, not the thumb mode.
The solution is to add
-mcpu=cortex-m0plus
for these Kinetis-L projects to the compiler 'Other target flags'.
The following sections provide more detailed information about the differences.
Differences
Both the 'launchpad' and the 'legacy' toolchains are GNU toolchains, and largely compatible. However there are notable differences between the two toolchains:
| legacy | launchpad | |
|---|---|---|
| GNU Binaries | Microsoft 32bit binaries, Linux 64bit binaries | Microsoft 32bit binaries, Linux 32bit binaries(1) |
| GNU binutils | 2.32.2 | 2.23.2.20140731(*) |
| GCC | 4.8.0(*) | 4.8.4 (ARM/embedded-4_8-branch) |
| NewLib | 1.19.0(*) | 2.1.0(*) |
| Newlib-nano | 1.0(*) | 2.1 |
| GDB | 7.6(2) | 7.6.0.20140731-cvs(2) |
| ARM Mode | Thumb | ARM (non-Thumb) |
(*) Modified.
(1) See next section about running 32bit GNU tools on 64bit Linux.
(2) The legacy GDB has Python support, while this is not present in the launchpad 4.8-2014-q3 build. Python support has been added by ARM in 4.9-Q4-2014 release.
Launchpad 32bit Binaries to run on 64bit Linux
Because the 'launchpad' tools are 32bit binaries on Linux only, this can cause issues on 64bit Linux systems (e.g. Ubuntu 14.04 64bit) if the needed 32bit support libraries are not installed. A usual error message is that arm-none-eabi-gcc could not be found, even if that file is present, because the system does not know how to run it. This is because the 'launchpad' tools are built as 32bit binaries, an the compatibility package needs to be installed. See http://gnuarmeclipse.livius.net/blog/toolchain-install/ how to install the necessary compatibility libraries for Linux.
ARM Default Mode
The default options for the 'legacy' toolchain produce code for the ARM Cortex-M0+ (Thumb mode), while the 'launchpad' tools default to the 'ARM' mode (non-Thumb). Therefore it is important that the command line options -mthumb with the appropriate -mcpu= or -march= options are used if using the tools in command line only mode. If using the GNU ARM Eclipse plugins, then no changes are needed as these options are set in the project already:
Default Libraries and Options
The GNU compiler driver and linker is using default pre-built libraries in certain sub directories. These directories contain a default set of libraries, based on the compiler and architecture options specified during the build and link phase. Using linker options like -L to include a specific library or using options like -nostdlib or similar have an effect which libraries in which subdirectory are used. The library folder location is in <KDS_Installation_PATH>\toolchain\arm-none-eabi\lib
The following table lists the specific options used for both the legacy tools and launchpad tools to link for a specific architecture and floating point ABI used:
| Target | Legacy Options | Legacy Subdir | Launchpad Options | Launchpad Subdir |
|---|---|---|---|---|
| ARM Cortex-M0+ | <default> | <default> | -mthumb -march=armv6s-m | armv6-m |
| ARM Cortex-M4 | -mcpu=cortex-m4 | m4 | -mthumb -march=armv7e-m | armv7e-m |
| ARM Cortex-M4F | -mcpu=cortex-m4 -mfloat-abi=hard -mfpu=fpv4-sp-d16 | m4/fp/v4-sp-d16 | -mthumb -march=armv7e-m -mfloat-abi=hard -mfpu=fpv4-sp-d16 | armv7e-m/fpu |
| ARM Cortex-M4F with softfp ABI | -mcpu=cortex-m4 | m4 | -mthumb -march=armv7e-m -mfloat-abi=softfp -mfpu=fpv4-sp-d16 | arm7e-m/softfp |
Newlib-nano
Both the legacy and the launchpad toolchain include the newlib-nano library, a standard library more optimized for embedded devices than the normal newlib one. The option to select the newlib-nano library is different:
| Newlib-nano for Legacy | Newlib-nano for Launchpad |
|---|---|
| -nanolibc | --specs=nano.specs |
Application _start()
The startup code needs to call the _start() function of the library which then calls the main() function. The _start() function in the library is responsible to initialize the library and prepare it to be used by the application. In order to do this, the library needs to have the __stack symbol defined in the linker file which points to the top of stack. For this, the __stack symbol needs to be defined in the linker file as in the example below:
/* Highest address of the user mode stack */
_estack = 0x20000000; /* end of m_data */
__SP_INIT = _estack;
__stack = _estack;
Semihosting
The legacy library has semihosting included in the libraries, and users can use _isatty() and _write() to overwrite the existing semihosting hooks. With the launchpad tools semihosting is enabled with the -specs=rdimon.specs linker option, and users can implement their own hooks with _sbrk(), _write(), _close(), _fstat(), _isatty(), _lseek() and _read(). To completely disable semihosting, the options -specs=nosys.specs can be passed to the linker.
Application Exit Function
The legacy library includes a default implementation of _exit(), while the launchpad tools do not include this. Using the -specs=nosys.specs linker option will ensure that the linker does not complain about the missing _exit() function.
Summary
A typical legacy Kinetis Design Studio (KDS) V2.0.0 project can be easily migrated to the launchpad toolchain with adding -specs=nosys.specs linker option and replacing the -nanolibc legacy option with -specs=nano.specs linker option.
Links
- Kinetis Design Studio: Kinetis Design Studio Integrated Development |Freescale
- GNU Tools for ARM Embedded: GCC ARM Embedded in Launchpad
- Q3 2014 GNU Tools for ARM Embedded Release: 4.8-2014-q3-update : Series 4.8 : GCC ARM Embedded
- Blog article about how to switch KDS toolchain: Switching ARM GNU Tool Chain and Libraries in Kinetis Design Studio | MCU on Eclipse
- GNU ARM Eclipse plugin website and blog by Liviu: Welcome to the GNU ARM Eclipse plug-ins! | GNU ARM Eclipse
- Article by Liviu how to install toolchain: http://gnuarmeclipse.livius.net/blog/toolchain-install/
Hi BlackNight, thanks for sharing this document. I have a question regarding the project conversion process. For those project previously written using KSDK 1.1, KDS 3.0 is going to ask us to install the KSDK 1.1.0-GA update:
When I first loaded the project, I clicked "Skip loading", and then proceeded with the project conversion. It completed successfully. My thought was that after closing and re-opening the upgraded project, I would no longer get this message. However, that's not the case.
At this point, I'm not sure what to do because I don't know how the 1.1.0-GA update will interact in KDS 3 when the 1.2.0-GA update is already installed. I do know that clicking Continue loading results in a project that doesn't work.
Hi Erich,
I have tried to use the "KDS upgrade assistant" tool to migrate KDS2.0 projects with KSDK1.1 to KDS3.0 version. I am trying to convert the KSDK libs, MQX libs, USBH libs and usb host demo projects. All succeeded except the usb host demo.
I got a failure message as follows.
Project name: host_msd_fatfs_frdmk64f_mqx_frdmk64f
Project location: C:/Freescale/KSDK_1.1.0/usb/example/host/msd/msd_fatfs/sdk/kds/host_msd_fatfs_frdmk64f_mqx
Conversion status: failure.
Add exit() file failure: A resource exists with a different case: '/host_msd_fatfs_frdmk64f_mqx_frdmk64f/sources'.
So do I need to apply the last step in upgrade option?
Hao
