Getting Started with
Freescale MQX™ RTOS and
IAR Embedded Workbench
PRODUCT: Freescale MQX™ RTOS
PRODUCT VERSION: Freescale MQX 3.6.1 (or later)
DESCRIPTION: Using IAR Embedded Workbench Tools with Freescale MQX™ RTOS
nd
RELEASE DATE: Sep 22 , 2010
© Freescale Semiconductor, Inc., 2010. All rights reserved.
How to Reach Us:
Home Page:
www.freescale.com
Web Support:
http://www.freescale.com/support
USA/Europe or Locations Not Listed:
Freescale Semiconductor, Inc.
Technical Information Center, EL516
2100 East Elliot Road
Tempe, Arizona 85284
1-800-521-6274 or +1-480-768-2130
www.freescale.com/support
Europe, Middle East, and Africa:
Freescale Halbleiter Deutschland GmbH
Technical Information Center
Schatzbogen 7
81829 Muenchen, Germany
+44 1296 380 456 (English)
+46 8 52200080 (English)
+49 89 92103 559 (German)
+33 1 69 35 48 48 (French)
www.freescale.com/support
Japan:
Freescale Semiconductor Japan Ltd. Information in this document is provided solely to enable system and
Headquarters software implementers to use Freescale Semiconductor products. There are
no express or implied copyright licenses granted hereunder to design or
ARCO Tower 15F fabricate any integrated circuits or integrated circuits based on the
1-8-1, Shimo-Meguro, Meguro-ku, information in this document.
Tokyo 153-0064
Japan Freescale Semiconductor reserves the right to make changes without further
notice to any products herein. Freescale Semiconductor makes no warranty,
0120 191014 or +81 3 5437 9125 representation or guarantee regarding the suitability of its products for any
[email protected] particular purpose, nor does Freescale Semiconductor assume any liability
arising out of the application or use of any product or circuit, and specifically
disclaims any and all liability, including without limitation consequential or
Asia/Pacific: incidental damages. “Typical” parameters that may be provided in Freescale
Freescale Semiconductor China Ltd. Semiconductor data sheets and/or specifications can and do vary in different
Exchange Building 23F applications and actual performance may vary over time. All operating
parameters, including “Typicals”, must be validated for each customer
No. 118 Jianguo Road application by customer’s technical experts. Freescale Semiconductor does
Chaoyang District not convey any license under its patent rights nor the rights of others.
Beijing 100022 Freescale Semiconductor products are not designed, intended, or authorized
for use as components in systems intended for surgical implant into the body,
China or other applications intended to support or sustain life, or for any other
+86 10 5879 8000 application in which the failure of the Freescale Semiconductor product could
[email protected] create a situation where personal injury or death may occur. Should Buyer
purchase or use Freescale Semiconductor products for any such unintended
or unauthorized application, Buyer shall indemnify and hold Freescale
For Literature Requests Only: Semiconductor and its officers, employees, subsidiaries, affiliates, and
Freescale Semiconductor Literature Distribution Center distributors harmless against all claims, costs, damages, and expenses, and
reasonable attorney fees arising out of, directly or indirectly, any claim of
P.O. Box 5405 personal injury or death associated with such unintended or unauthorized
Denver, Colorado 80217 use, even if such claim alleges that Freescale Semiconductor was negligent
1-800-441-2447 or +1-303-675-2140 regarding the design or manufacture of the part.
Fax: +1-303-675-2150
[email protected]
Freescale™ and the Freescale logo are trademarks of Freescale
Semiconductor, Inc. ARC, the ARC logo, ARCangel, ARCform, ARChitect,
ARCompact, ARCtangent, BlueForm, CASSEIA, High C/C++, High C++,
iCon186, MetaDeveloper, MQX, Precise Solution, Precise/BlazeNet,
Precise/EDS, Precise/MFS, Precise/MQX, Precise/MQX Test Suites,
Precise/RTCS, RTCS, SeeCode, TotalCore, Turbo186, Turbo86, V8 µ RISC,
V8 microRISC, and VAutomation are trademarks of ARC International. High C
and MetaWare are registered under ARC International.
All other product or service names are the property of their respective owners.
© Freescale Semiconductor, Inc. 2010. All rights reserved.
Rev. 01
09/2010
Table of Contents
1 Read Me First .................................................................................................................................. 2
2 Building the MQX Libraries ........................................................................................................... 3
2.1 Compile-time Configuration ....................................................................................................... 3
2.2 Build Configurations ................................................................................................................... 4
2.3 Batch Build in IAR Embedded Workbench IDE ......................................................................... 4
3 MQX Task Aware Debugging ......................................................................................................... 6
3.1 Debugging MQX Applications in IAR Embedded Workbench ................................................... 6
3.2 TAD CSpy Debugger Plug-in ..................................................................................................... 7
Getting Started with Freescale MQX™ RTOS and IAR Embedded Workbench
Freescale Semiconductor 1
1 Read Me First
This document describes steps required to configure the IAR Embedded Workbench development
tools and use it to build, run and debug applications of the Freescale MQX™ RTOS operating
system. Refer to “Getting Started” and other user documentation included within the latest
Freescale MQX™ RTOS installation for more details not specifically related to IAR Embedded
Workbench tools.
Get the latest Freescale MQX™ RTOS at http://www.freescale.com/mqx.
Freescale MQX Getting Started
2 Freescale Semiconductor
2 Building the MQX Libraries
2.1 Compile-time Configuration
Major compile-time configuration options are centralized in a single user configuration file located in
<install_dir>/config/<board>/user_config.h
This user configuration file is included internally by private configuration files in MQX PSP and BSP.
To share configuration settings between different boards, the user_config.h file may include other
header files with common settings. The header files may only be located in the same <board>
directory or in the “common” directory:
<install_dir>/config/common
All MQX configuration files are also indirectly used by other core components like RTCS, MFS, etc.
“Indirectly” means that the MQX PSP and BSP must be build first, which causes the configuration
file being copied into the output (lib) directory. The other components then include the configuration
file from the /lib output directory.
Caution: Until the PSP or BSP libraries are rebuilt, configuration changes made in the
user_config.h file are not used by any other MQX component. On the other hand, after the PSP
and BSP libraries are re-compiled with a new configuration, it is important to recompile the other
libraries so the compiled code is consistent with the configuration file. See the next section for more
details.
2.1.1 Build Process
After any change to the compile-time user configuration file or MQX kernel source files, the MQX
libraries need to be re-built. The build process is similar with all core components:
- The output directory is <install_dir>/lib/<board>.<compiler>/<component>
- For example the MQX PSP and BSP libraries for M52259EVB board are built into the
/lib/m52259evb.iar/mqx directory.
- All public header files needed by application to make use of the library are automatically
copied from internal include folders to the same output directory as the library itself.
- During PSP or BSP build process, also the user_config.h file and other header files from
the config/<board> and config/common directories are copied into the lib/<board>.iar
output directory.
- Other components like RTCS, MFS, etc. use the copied configuration files only.
- Similarly as the PSP and BSP, the other libraries build into the output directories inside
/lib/<board>.iar
To summarize the points above, there are simple rules to obey when re-building the MQX libraries.
- After any change to the /config/common/user_config.h file, all MQX libraries should be
re-built.
- The PSP and BSP libraries must be build first, before the MFS, RTCS and other libraries.
- Important: No changes should be made to header files in the output build directory (/lib).
The files get overwritten any time the libraries are built.
Getting Started with Freescale MQX™ RTOS and IAR Embedded Workbench
Freescale Semiconductor 3
2.2 Build Configurations
Each IAR project in Freescale MQX™ RTOS contains multiple compiler/linker configurations (so
called build „targets“).
Two different types of build targets exist for different compiler optimization settings:
- Debug – the compiler optimizations are turned off or set to low. The compiled code is easy
to debug but may be less effective and much larger than the Release build. All output
libraries (or executables) have _d postfix in the file name (e.g. rtcs_<board>_d.a).
- Release – the compiler optimizations are set to maximum. The compiled code is very hard
to debug and should be used for final applications only. There is no postfix in the output file
name (e.g. rtcs_<board>.a).
Build target name of any MQX application project makes a reference either to Debug or Release
builds of the core libraries. On top of that the target names also specify board memory configuration
which gets built. For example:
Devices with internal Flash memory (e.g. MCF522xx):
- Int. Flash Release – this target is suitable for final application deployment. When
programmed to Flash, the application starts immediately after reset. Variables are allocated
in internal SRAM memory.
- Int. Flash Debug – same as above, only the Debug-compiled libraries are used. This target
is suitable for debugging before deployment. On boards without external memory, this is the
only target suitable for debugging larger applications.
Boards with external MRAM memory (M52259EVB etc.):
Ext. MRAM Debug – solely for debugging purposes with code located in external MRAM
memory (available e.g. on the M52259EVB). Variables are located in internal SRAM. Part of
the external MRAM memory may also be used for additional RAM memory pools.
Application executable is loaded to MRAM automatically by the debugger.
Boards with external RAM memory (M54455EVB etc.):
Ext. Ram Debug – solely for debugging purposes with code located in external RAM
memory (available as SDRAM e.g. on the M54455EVB). Both code and variables are
located in this external memory. Application executable is loaded to RAM automatically by
the debugger.
Refer to BSP-specific information included in the latest MQX installation for description of build
targets specific to particular boards.
2.3 Batch Build in IAR Embedded Workbench IDE
With IAR, the MQX build process can be simplified by using Batch Build feature. For each supported
board, there is an IAR Workspace file which includes build projects for all related MQX libraries:
<install_dir>/config/<board>/iar/build_libs.eww
The Workspace file contains Batch Build configurations which can be used to build all MQX libraries
at once.
- Go to menu “Project / Batch Build” or press the F8 key in the IAR IDE.
Freescale MQX Getting Started
4 Freescale Semiconductor
- Select Batch configuration to build (refer to next section for more details about build targets)
- Press the “Make” button to start the batch build process.
Getting Started with Freescale MQX™ RTOS and IAR Embedded Workbench
Freescale Semiconductor 5
3 MQX Task Aware Debugging
MQX Task Aware Debugging plug-in (TAD) is an optional extension to a debugger tool which
enables easy debugging of multi-tasking applications. It helps to visualize internal MQX data
structures, task-specific information, I/O device drivers and other MQX context data.
3.1 Debugging MQX Applications in IAR Embedded Workbench
Loading and debugging MQX applications is an easy task with IAR Embedded Workbench tool and
it is not different from debugging classic non-OS applications. Make sure the correct debugger
interface is selected in the project options and correct processor initialization Macro file is used.
MQX installation contains its own processor initialization macro files as a part of the BSP library for
each supported processor.
When an MQX application is compiled and linked with all MQX libraries, press the “Download and
Debug” button on the toolbar. The application gets executed and stops at the default C language
entry point in the main() function. Be aware that at this breakpoint, the MQX Operating System is
not yet running so use of TAD plugin features (as described in later sections) is limited.
Freescale MQX Getting Started
6 Freescale Semiconductor
3.2 TAD CSpy Debugger Plug-in
3.2.1 Installing CodeWarrior TAD
TAD plug-in DLL is pre-installed in IAR Embedded Workbench automatically. In case you need to
update the plug-in to a new version included with the latest MQX installation, perform the following
manual installation steps:
1. Close the IAR Embedded Workbench IDE
2. Locate the tools\iar_extensions\<platform> directory in Freescale MQX™ RTOS
installation folder (by default C:\Program Files\Freescale\Freescale MQX x.y)
3. Copy the entire content of tools\codewarrior_extensions\<platform> directory to the IAR
Embedded Workbench installation folder (e.g.
C:\Program Files\IAR Systems\Embedded Workbench 5.5\cf)
4. After the steps above are done, verify the TAD plugin files exist at the new location:
<EW>\<platform>\plugins\rtos\MQX\MQXRtosPlugin.ewplugin
<EW>\<platform>\plugins\rtos\MQX\MQXRtosPlugin<PLATFORM>.dll"
5. Re-start IAR Embedded Workbench IDE.
6. In the Embedded Workbench environment, you should be now able to enable MQX TAD by
selecting “MQX” in the “Plugins” tab of the “Debugger” panel of project settings. All example
applications coming with Freescale MQX™ RTOS are already configured so.
Getting Started with Freescale MQX™ RTOS and IAR Embedded Workbench
Freescale Semiconductor 7
3.2.2 Using MQX TAD Screens
Using the MQX or RTCS menu in IAR IDE main window, several TAD “screens” may be opened
during the debugging session.
The most helpful and frequently used screens are shown in the pictures below:
Task Summary – overview about all tasks created in the MQX application.
Freescale MQX Getting Started
8 Freescale Semiconductor
Stack Usage Summary – displays information about interrupt and task stacks. Typically,
stack overflow is a root cause of vast majority of problems in MQX user applications.
Memory Block Summary (or Lightweight Memory Block Summary) – displays address, size
and type information about each memory block allocated in the default memory pool by the
MQX system or applications. Additional memory pools (if used) may be displayed using the
“Memory Pools” screen.
Semaphores, Events (or Lightweight Semaphores, Lightweight Events) – displays address
and status of synchronization objects created by the MQX system or application. When a
synchronization object is allocated as a global or static variable in the system, as an array
element or as a structure member allocated as global or static variable, the TAD plug-in also
displays the symbolic name of the object.
Getting Started with Freescale MQX™ RTOS and IAR Embedded Workbench
Freescale Semiconductor 9
3.2.3 Task-aware Debugging
The TAD plug-in also provides native debugger support for multi-tasking MQX environment.
Individual tasks can be examined any time the application stops on breakpoint or when it is stopped
manually by pressing the “Break” red-hand toolbar button.
In the MQX menu in the IAR IDE main window, select the “Task List” item at top of the menu. The
Task List view will open at the top of the window and will give you a list of all running tasks.
The Green Arrow icon indicates which task was active at the moment of break.
The Lens icon indicates which task context is currently examined in the debugger in terms
of execution point, register values, etc. Double click task items in the “Task List” view to
move the lens and examine other tasks.
Freescale MQX Getting Started
10 Freescale Semiconductor
