This is the start of a multi-post tutorial about the Freescale Kinetis SDK, released back in April as beta version. The SDK a set of peripheral drivers, and will become the standard software foundation and drivers provided by Freescale for their ARM Cortex based devices. Similar what other vendors already do. While this is a good step, it is the same time very disruptive for my university projects with new Freescale Cortex-M devices. And with everything new (and beta), it needs time to learn. So this post is about creating a Do-It-Yourself Kinetis SDK project from scratch for Eclipse. This part is about the startup code: about everything to get the application started.

Learning new stuff?

Typically I have two kind of students:

• Type 1 is looking for something already set-up and working. Does not want to know about all the details. All what he cares about is reaching the goals, e.g. passing the exam or have his lab assignment working.

• Type 2: As type 1 does want to reach the goal too. But wants to understand and know the details behind it, down to the bits and bytes.

Type 1 is what is more ‘extrinsic’ (externally) motivated, while Type 2 is more ‘intrinsic’ (internally) motivated. Type 1 typically has more problems later to apply the knowledge to similar situations, while Type 2 needs to be careful to balance between how much to go into the details without loosing the final goal out of sight.

It is the same way with developing software or using tools: many prefer to just have an example and then go with it. Others want to build up something from scratch (DIY: Do-It-Yourself) and know every detail. To some extend it is a typical ‘make or buy’ decision: each approach has its justification.

Creating (instead of buying) needs time, but has the opportunity to gain knowledge. But creating can be painful if it does not work the right way, or if at the end the result is not achieved. This tutorial is for the DIY readers, as it goes through the steps to build an initial project for the Freescale Kinetis SDK with Eclipse IDE, GNU ARM Embedded and the GNU ARM Eclipse plugins.

If you are a Type 1 person (and still reading this): scroll to the end of this article, and you find the link to download the project from GitHub ;-).

Eclipse Kepler and Kinetis Design Studio (KDS)

By default, this tutorial is using my classroom IDE with Eclipse Kepler and GNU ARM Embedded toolchain (see “Constructing a Classroom IDE with Eclipse for ARM“). Many of the steps outlined in this tutorial are performed by the ‘new project wizard’ inside the Kinetis Design Studio (KDS). I have outlined the differences in my text below. So if you are using KDS, then many settings will ‘magically’ in place which makes things easy. However, this does not give you the knowledge about *what* is configured, and *why* things are the way configured as they are. So I believe even if you are KDS, this tutorial is of value for you because it makes a deep dive into the mechanics and settings for a KDS project. I hope that makes sense? And as a side effect it allows you to work around some of the KDS beta version issues.

Freescale Kinetis SDK

The Freescale Kinetis SDK is available as beta download from

http://www.freescale.com/ksdk

. It is basically a set of drivers (UART, SPI, I2C, …) with API for the Freescale Kinetis (ARM) microcontroller. It comes with a very permissible open source license attached which makes it attractive. It has a hardware abstraction layer and the ability to plug-in operating systems with an Operating System Abstraction (OSA) like MQX, uCOS and FreeRTOS, but is bare-metal (no RTOS) by default. It is the first time Freescale really adopts CMSIS (the standard for ARM cores). Unfortunately, the Freescale Kinetis SDK is quite complex and not easy to setup (at least with the current beta). And this is the reason for this tutorial: showing how to set up a ‘bare’ project in Eclipse which then can be extended more functionality later on.

The Kinetis SDK comes with make files to build it. You need to be a make file expert to understand all the distributed make files which is beyond the scope of this tutorial. Because of the complex and many directory structure, it is not easy to use the SDK with an IDE like Eclipse neither. So let’s have a look at the directories:

• apps: has demo applications.
• boards: has board configuration which have the peripherals of a particular board (e.g. LED, accelerometer, etc) configured.
• doc: has API reference manuals and getting started guides.
• lib: the purpose of this folder is to contain pre-build libraries of SDK configurations.
• mk: has common make files
• platform: this has the core of the SDK with many sub folders, including the CMSIS.
• CMSIS: has the CMSIS-CORE and CMSIS-DSP files.
• drivers: has device drivers like UART, SPI, I2C, …
• hal: hardware abstraction layer for the device drivers.
• linker: has linker files
• startup: has C/C++ startup files
• utilities: common utility functions. Weired part is that it contains the SDK OS (Operating System) abstraction too?
• rtos: The SDK itself does not come with any RTOS (it comes as ‘bare metal’), but is prepared that an RTOS (FreeRTOS, MQX, uCOS, …) can be plugged in here.
• usb: USB stack sources are here.

With this high level overview knowing what is in the SDK, we can start to create a project with it.

Preconditions

For this tutorial you need:

1. Eclipse Kepler IDE with GNU ARM Embedded toolchain and GNU ARM Eclipse plugins. See “Constructing a Classroom IDE with Eclipse for ARM” how to build such a toolchain.
2. Kinetis SDK downloaded and installed. You can download it fromhttp://www.freescale.com/ksdk

   . I have Eclipse variable ${KSDK_PATH} pointing to the installation location.

3. Because the SDK only supports a few devices as of today, I’m using the FRDM-K64F board. If you have a different board, then you can use the steps below, just use a different board name.

To have things independent where the SDK is installed, I have two variables defined in my workspace: ${KSDK_PATH} and KSDK_LOC:

${KSDK_PATH} is used for the GNU build tools to find the header files/etc:

KSDK_LOC is used for linking files in the project:

Using that KSDK_LOC variable, I can make my linked files using it:

Outline

I’m going through the baby steps to create a project, add the needed files to have at the end a project running with the Kinetis SDK. So with this you learn which files you need and how to configure a project from scratch. The project does not do anything at the end, so this will be subject of a next tutorial (to be written).

So let’s start…

Creating Empty Project

First, I need to create a new project:

💡 For KDS, use the menu File > New > Kinetis Design Studio Project, and then only select the SDK option (Processor Expert option not enabled).

1. Menu File > New > C Project:
   

   New Kinetis SDK Project

2. Provide a project name and select ‘Empty project’ for ‘Cross ARM GCC’:
   

   Empty Cross ARM Project

3. Use the defaults in the other wizard dialogs, and have the project created.

And I have what I asked for: an empty project 🙂 :

Compiler Settings

The project is a default one, so the first thing to do is to verify that it is generating the code needed for my CPU. I’m using here the FRDM-K64F board which has an ARM Cortex-M4F. The ‘F’ suffix means it has a hardware floating point. So I go to the project settings (select the project, menu Project > Properties > C/C++ Build > Settings) and configure it for

1. Cortex-M4
2. FP instructions (hard)
3. fpv4-sp-d16

💡 The KDS project wizard already should have set the correct settings as shown in the screenshot.

Startup code

The first thing I need for my project is the startup code. The startup code sets program counter and stack pointer, configures my hardware (clock speed, clock gates, …), initialize my global variables and then jumps to main(). The Kinetis SDK comes with a startup code which I’m going to add.

💡 I’m creating here folders (context menu on project,  New > Folder) to ‘mimic’ the Kinetis SDK folder structure, and have then ‘link to files’ to the files in the Kinetis SDK structure. The Kinetis SDK has many, many sub folders, and this makes it really hard to find files, and requires to setup many compiler include paths. So creating the folder structure in my project helps me to visualize from where I’m taking the files. Of course you can use another way (e.g. copy all the needed files into a folder inside your project). Actually that copy method is not a bad idea, but not used here. Just experiment and use the way which fits you best.

The startup for my board needs three files:

❗ I’m using ‘link to files’ here for the startup code, as I’m not going to change the startup files. However, some times it is necessary to change the startup files for the application needs. In this case, make sure you *copy* the files to your project, otherwise you are changing the content of the SDK!

1. ${KSDK_SDK}\platform\startup\startup.c: initialization of global memory and variables.
2. ${KSDK_SDK}\platform\MK64F12\system_MK64F12.c: this configures the ‘system’ with clock configuration.
3. ${KSDK_SDK}\platform\MK64F12\gcc\startup_MK64F12.S: the application entry point from the reset vector, written in assembly.

💡 The KDS project wizard has copied the system and startup files to the project at project creation time.

It is important to understand the sequence of the startup:

1. At hardware reset, the processor fetches the initial stack pointer and initial program counter from the reset vector. Typically the PC then points to the Reset_Handler.
2. The reset handler performs system initialization, initialize the memory and library. Each step can be configured with assembler macros (see below).
3. System initialization is peformed to configure watchdog, initial clock settings or things like enabling the Floating Point Unit (FPU) if present.
4. The bss data (global memory) gets initialized.
5. As last step it calls the library (C Runtime, crt) _start routine. This initializes the runtime/ANSI library. This part then calls the application main() routine.

Each of the steps can be configured with assembler preprocessor macros, more about this later.

CMSIS Include Headers

If I would now try to compile it, it will result in errors because header files are not found:

${KSDK_PATH}/platform/startup/startup.c:31:41: fatal error: device/fsl_device_registers.h: No such file or directory
 #include "device/fsl_device_registers.h"

So I need to add the following CMSIS paths to my compiler include paths (-I option):

💡 The KDS new project wizard already has these paths configured.

"${KSDK_PATH}/platform/CMSIS"
"${KSDK_PATH}/platform/CMSIS/Include"
"${KSDK_PATH}/platform/CMSIS/Include/device"

💡 I’m using an Eclipse variable KDSK_PATH to point to the SDK location, so if I move my project or the SDK, I only need to update one variable.
💡 As a tip, you can copy/paste the paths into the settings panel.

💡 Question: How to know where the folder is? Answer: I use the Windows Explorer and search inside the SDK folder for the files.

CPU Compiler Preprocessor Macro/Define

Now if I build, it will find the header files, but will stop with another error:

💡 The KDS project created by the wizard already has the CPU preprocessor macro configured.

${KSDK_PATH}/platform/CMSIS/Include/device/fsl_device_registers.h:569:6: error: #error "No valid CPU defined!"
 #error "No valid CPU defined!"

The thing is that the SDK needs to know the CPU I’m compiling for as a compiler preprocessor macro/define. To know which define it is expecting, I open the file fsl_device_registers.h and search/look for my CPU (MK64F in my case). This gets me to this section (around line 235):

#elif (defined(CPU_MK64FX512VDC12) || defined(CPU_MK64FN1M0VDC12) || defined(CPU_MK64FX512VLL12) || \
    defined(CPU_MK64FN1M0VLL12) || defined(CPU_MK64FX512VLQ12) || defined(CPU_MK64FN1M0VLQ12) || \
    defined(CPU_MK64FX512VMD12) || defined(CPU_MK64FN1M0VMD12))
    #define K64F12_SERIES

    /* Extension register headers. (These will eventually be merged into the CMSIS-style header.)*/
    #include "device/MK64F12/MK64F12_adc.h"

I have the MK64FN1M0VLL12 on my board, so I specify this in the compiler preprocessor settings:
💡 I use a magnifying glass to read the tiny writing of the device on the board.
Preprocessor Setting to Specify the SDK Derivative
main()
Now it compiles my startup code, and the linker kicks in. But it will report that it cannot find main():
'Invoking: Cross ARM C Linker'
arm-none-eabi-gcc -mcpu=cortex-m4 -mthumb -mfloat-abi=hard -mfpu=fpv4-sp-d16 -O0 -fmessage-length=0 -fsigned-char -ffunction-sections -fdata-sections  -g3 -Xlinker --gc-sections -Wl,-Map,"FRDM-K64F_Bare_SDK.map" -o "FRDM-K64F_Bare_SDK.elf"  ./Sources/main.o  ./SDK/platform/startup/MK64F12/gcc/startup_MK64F12.o  ./SDK/platform/startup/MK64F12/system_MK64F12.o  ./SDK/platform/startup/startup.o   
c:/tools/ide/gcc/bin/../lib/gcc/arm-none-eabi/4.8.3/../../../../arm-none-eabi/lib/armv7e-m/fpu\libg.a(lib_a-exit.o): In function `exit':
exit.c:(.text.exit+0x16): undefined reference to `_exit'
c:/tools/ide/gcc/bin/../lib/gcc/arm-none-eabi/4.8.3/../../../../arm-none-eabi/lib/armv7e-m/fpu/crt0.o: In function `_start':
(.text+0x4a): undefined reference to `main'
collect2.exe: error: ld returned 1 exit status
make: *** [FRDM-K64F_Bare_SDK.elf] Error 1
My bad! So I add a main.c source file to my project:
Main.c added
Embedded programs never leave main(), so I add an endless loop to the end:
💡 The KDS wizard has already added main().
sss (copy in Text tab!)int main(void) {
  for(;;) {
    /* never leave main */
  }
}

Linker File
That linker error reminds me about an important thing missing so far: the linker file!
💡 Projects created with the KDS new project wizard have the linker file added.
The Kinetis SDK comes with a linker files for my microcontroller in
${KSDK_PATH}\platform\linker\gcc\K64F12
I tell the linker to use the FLASH file (K64FN1Mxxx12_flash.ld):
SDK Linker File
And I specify the path to the linker file(s) as “${KSDK_PATH}\platform\linker\gcc\K64F12”:
Linker Library Search Path
 Linker and Libraries
Building the project still reports a linker error:
❗ KDS is *not* using the standard GNU ARM Embedded (launchpad) toolchain. It is having some differences how the linker handles things, and that linker seems to automatically link things differently.
'Invoking: Cross ARM C Linker'
arm-none-eabi-gcc -mcpu=cortex-m4 -mthumb -mfloat-abi=hard -mfpu=fpv4-sp-d16 -O0 -fmessage-length=0 -fsigned-char -ffunction-sections -fdata-sections  -g3 -T K64FN1Mxxx12_flash.ld -Xlinker --gc-sections -L"C:\Freescale\KSDK_1.0.0-Beta\platform\linker\gcc\K64F12" -Wl,-Map,"FRDM-K64F_Bare_SDK.map" -o "FRDM-K64F_Bare_SDK.elf"  ./Sources/main.o  ./SDK/platform/startup/MK64F12/gcc/startup_MK64F12.o  ./SDK/platform/startup/MK64F12/system_MK64F12.o  ./SDK/platform/startup/startup.o   
c:/tools/ide/gcc/bin/../lib/gcc/arm-none-eabi/4.8.3/../../../../arm-none-eabi/lib/armv7e-m/fpu\libg.a(lib_a-exit.o): In function `exit':
exit.c:(.text.exit+0x16): undefined reference to `_exit'
collect2.exe: error: ld returned 1 exit status
make: *** [FRDM-K64F_Bare_SDK.elf] Error 1
So it means that my linker (or library) settings are not correct yet. _exit() is called at the end of main(), but as for an embedded program, I do not want (and need) to leave main.
Therefore I can add
-specs=nosys.specs
to the linker options which tells the linker not to include any special system library functionality.
Other Linker Flags
With this, I’m able to link:
'Invoking: Cross ARM GNU Print Size'
arm-none-eabi-size --format=berkeley "FRDM-K64F_Bare_SDK.elf"
   text       data        bss        dec        hex    filename
   2692       1088         28       3800        ed8    FRDM-K64F_Bare_SDK.elf
'Finished building: FRDM-K64F_Bare_SDK.siz'
Stack and Heap
There are a few things in the assembly startup file I can configure through assembler macros, as mentioned earlier. The first thing is the stack size. By default, it uses 4 KByte (0x1000):
#ifdef __STACK_SIZE
    .equ    Stack_Size, __STACK_SIZE
#else
    .equ    Stack_Size, 0x00001000
#endif

The other thing is the heap size which is 4 KByte (0x1000) by default:
#ifdef __HEAP_SIZE
    .equ    Heap_Size, __HEAP_SIZE
#else
    .equ    Heap_Size, 0x00001000
#endif

If I don’t want to go with the defaults, I can tune this in the project settings as assembler preprocessor defines, e.g.
"__STACK_SIZE=0x0400"
"__HEAP_SIZE=0x00"
GNU Assembler Preprocessor Settings
❗ KDS beta V1.0.1 has here another another macro (“__START=main”) defined. Actually this is a bug, and that macro should be removed (it is documented in the KDS release notes).
Startup Configuration Macros
In a similar way, there are other configuration of the startup code with the __NO_SYSTEM_INIT and __NO_INIT_DATA_BSS macros, right at the start of the reset vector, and there is __START afterwards.
❗ Because KDS v1.0.1 beta does *not* add startup.c, you need to have the __NO_INIT_DATA_BSS macro defined!
__NO_SYSTEM_INIT and __NO_INIT_DATA_BSS

If __NO_SYSTEM_INIT is defined as assembler preprocessor macro, then no system initialization is performed. SystemInit() is defined in system_MK64F12.c and configures the watchdog and initial system clock. I recommend that you perform that SystemInit() unless have very specific needs and know what you are doing!
If __NO_INIT_DATA_BSS is defined as assembler preprocessor macro, then no bss (global variable initialization and vector table copy to RAM) is performed. The function init_data_bss() is located in startup.c. Disabling bss initialization can be useful if you take care about initialization of variales (and libraries!) inside the application itself. That way code size of the application can be reduced. Typically it is *not* recommended to disable bss initialization.
__START is defined by default to call _start() in the GNU library. If you are not going to use the library and no runtime, you can define your own symbol.

 Debugging
The last step is to download and debug the application on the board. We have not added any functionality yet. All what we have is the startup code. Create a debug configuration and download it to the board. If everything goes fine, you should end up at main():
Reached Main
Congratulations 🙂
Summary
The Kinetis SDK comes with startup code and device drivers. The current SDK structure makes it not easy to be used with an IDE. To build my application with the SDK, it is important to know how the startup code works, and how I can add and configure it to my ’empty’ project. This is painful at the beginning, but going through all the steps ensures that things are understood, and can be tweaked later as necessary. And as a benefit: you should now understand how and why KDS is doing things :-). And as an additional benefit: the project built with GNU ARM Embedded (launchpad) toolchain is a few bytes smaller then the one with the Kinetis GNU toolchain ;-).
If you are only interested in the finished project, then it is available on GitHub (for Eclipse Kepler).
Topics for a continuation of this tutorial, if there is enough interest: adding board support, adding a blinking LED, adding FreeRTOS, …
Happy Startuping 🙂

		
	
			

			
			
Share this:
Print
Email
Twitter
Facebook
LinkedIn
Tumblr
Pinterest
Pocket
WhatsApp
Telegram
Like Loading...


	
Related