How-To: Cortex-M4 (STM32F4xx) + ChibiOS/RT + Keil uVision

This is a detailed step-by-step guide which will help you to create and setup Keil uVision project based on Cortex-M4 (STM32F4xx) and ChibiOS/RT. Most of this information is general and can apply with minor changes to other MCUs.

Step #1: Create a new project

Run Keil uVision IDE and in the main menu select: «Project» ⇒ «New uVision Project…»

Create a new folder for your project, give a name for the project, and save it inside this folder:

Then it is needed to select a target MCU. Just select one from STMicroelectronics (or other) device list:

There is no need to copy a default startup-code (ChibiOS/RT has its own).

After that a new project is created and IDE is ready to work.

Step #2: Project settings

Click on the “Target Options…” button…

…and begin a setup of each project element. First of all there are MCU & IDE settings:

Reference frequency (“Xtal, MHz”) is not really need to be changed. This option is only responsible for the startup-code generation, which is not used here. Instead of that ChibiOS/RT has its own settings and a startup-code. Take a look at the IRAM2 option, this option is need to be changed:

IRAM1 – is a main MCU memory (Internal RAM), its size is 0x20000 = 131072 bytes = 128 kbytes. IRAM2 – would be a top of a stack, its size was explicitly set to 1 byte just to indicate it as a valid value for IDE. Stack is used by ChibiOS/RT threads.

“Output” tab:

Turn off debug information if you don't need it. (For the first time debug info would help you in project development, so it is better to keep it enabled here).

The same for listing files: if you don't require them, disable them:

“User” tab usually don't require any changes:

Next, before to continue a project setup, lets prepare some useful files and folders. (NOTE: There are many possibilities to design and support a project. This is only a one good example).

In the project folder create two new folders: conf & os. Copy all the configuration files (ChibiOS/RT + your own) in conf folder. As a starting example use configuration files from the ChibiOS/RT demos (see Chibios/demos). In os copy all content from the same folder in ChibiOS/RT distributive. Doing a such way will result in an independent project setup. You will able to change anything you need in the RTOS source code without affecting other your projects. At the other hand, when you wouldn't make any changes in the ChibiOS/RT source code, it would be easier to upgrade one ChibiOS/RT version to another: just copy a new os folder content instead of an old one. Don't place any of your custom files in the “os” folder! Keep os exclusive to ChibiOS/RT.

Edit configuration files, if needed. It's an easy task because all of them are well documented.

“C/C++” tab require attention:

Important settings are highlighted. It is better to copy-paste a “Define” string from the working example, rather then to enter in manually. Also it is needed to add some include-paths:

This can be done by clicking on the button shown above and entering one or another include-path:

Add a list of a folders (include-paths) like in this example:

A complete list would looks something like this:

After this step a “C/C++” tab would looks like this:

Now skip to the “Asm” tab:

In a such way as for “C/C++” tab add include-paths for assembler:

An “Asm” tab after that:

A “Linker” tab usually don't require any changes in it:

At the “Debug” tab choose a debugger you prefer and perform its settings. The example below shows this with a ST-Link debugger:

ST-Link debugger is usually used with “SW” port. With a connected debugger and a board this tab would show a target MCU.

Subtab “Trace” (in “Debug” ⇒ “Settings”):

You could change the “Core Clock” setting to 168 MHz, if you need to trace your code or perform precise clock time measurements under debugger. In subtab “Flash Download” (in “Debug” ⇒ “Settings”) choose the right flash download algorithm (if it were not selected automatically):

In “Utilities” tab (project settings) also select a debugger you prefer:

At this step project configuration is complete.

Step #3: Software

Create a main project file main.c (other names are also allowed):

In the source code example below there is a very simple program with a ChibiOS/RT usage:

In this program: ChibiOS/RT initialized at first, then a new thread with a working function Thread1() is created. Both threads (main & Thread1) are only perform blinking of a LEDs, but with different intervals. This is a good starting point for STM32 + ChibiOS/RT newcomers.

Then it is desirable (but not mandatory) to prepare separate groups for different purposes. For your own files it could be a group with name main, for configuration - conf, for RTOS - os, hal, platform, port. Add other groups if needed. First of all, rename an existing group to main:

Then add other groups:

At the end it would looks like this:

This groups and their names are not related to the actual folder names. They are could coincide or be different. Names of groups are absolutely any. Groups are only a convenient way to keep common files in a one place.

Now add files to the groups.

Add main.c to the group main:

IDE would only complie those files which been added to the project (belongs to any of group). So, except for adding main.c it is needed to add all those ChibiOS/RT files which are really necessary for your project (or add all of them). A list of a really needed ChibiOS/RT files is depends on a RTOS configuration (see conf folder). In this example only a small subset of a ChibiOS/RT kernel files and a PAL peripheral for LEDs control are used.

Configuration files:

ChibiOS/RT kernel files:

HAL files:

Platform files:

A simple way to figure out a file source is to look at the example from ChibiOS/RT distributive. IDE has a menu item for that:

Each file could have it's own compiler settings!

Port files:

Step #4: Compilation

After the project setup and files addition/creation now it's to time compile them:

Compilation is in progress:

And the result:

NOTE: Try to add to the project only those files which are really needed. It would greatly speedup a compilation process!

Upon a compilation error, have a look at it description. If there is “an undefined function” or something, then this means that some file from ChibiOS/RT is required but not included. Look at the working example to figure out.

Step #5: Debug

Step-by-step debug is easy in Keil uVision:

The first instruction executed:

This is a part of a startup-code, which is always coded in assembler language. In order to skip to the main() function, just place a breakpoint at it and continue program execution.

It is also possible to tweak IDE to immediately skip to the main(), just enable it in the uVision project setup (“Debug” tab). There is also a special button to download program into the FLASH:

Step #6: Cleaning & Archiving

When all of your work under the project is complete, before commit it into SVN or before to send it to other developer, it is mandatory to clean it from intermediate files and other garbage:

After cleaning some files would stay:

A really useful from them are:

Now project could be commited to SVN. If you need a backup or want to send it via e-mail, then create an archive:

That's all! Good luck with Cortex-M4, ChibiOS/RT & Keil uVision!

Dmitry Gorokh UR4MCK 2012/10/12 11:08

chibios/community/guides/keil_uvision_chibios_rt_how-to.txt · Last modified: 2012/10/12 15:46 by daemon
Except where otherwise noted, content on this wiki is licensed under the following license:GNU Free Documentation License 1.3