Freescale Semiconductor MQX RTOS User manual

Freescale Semiconductor Document Number: MQXGSIAR
User’s Guide Rev. 5, 04/2015
© 2015 Freescale Semiconductor, Inc. All rights reserved.
Getting Started with
Freescale MQX™ RTOS and IAR
Embedded Workbench®
PRODUCT:
Freescale MQX™ RTOS
PRODUCT VERSION:
4.2.0
DESCRIPTION:
Using IAR Embedded Workbench Tools with Freescale MQX™ RTOS
RELEASE DATE:
April, 2015

Document Number: MQXGSIAR
Rev. 05, 04/2015
How to Reach Us:
Home Page:
www.freescale.com
Web Support:
http://www.freescale.com/support
Information in this document is provided solely to enable system and software
implementers to use Freescale products. There are no express or implied copyright
licenses granted hereunder to design or fabricate any integrated circuits based on
the information in this document.
Freescale reserves the right to make changes without further notice to any products
herein. Freescale makes no warranty, representation, or guarantee regarding the
suitability of its products for any particular purpose, nor does Freescale 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 incidental
damages. “Typical” parameters that may be provided in Freescale data sheets
and/or specifications can and do vary in different applications, and actual
performance may vary over time. All operating parameters, including “typicals,”
must be validated for each customer application by customer’s technical experts.
Freescale does not convey any license under its patent rights nor the rights of
others. Freescale sells products pursuant to standard terms and conditions of sale,
which can be found at the following address:
freescale.com/SalesTermsandConditions.
Freescale, the Freescale logo, and CodeWarrior are trademarks of Freescale
Semiconductor, Inc., Reg. U.S. Pat. & Tm. Off. Vybrid and Tower are
trademarks of Freescale Semiconductor, Inc. All other product or service
names are the property of their respective owners. ARM, ARM Powered logo,
and Cortex are registered trademarks of ARM Limited (or its subsidiaries) in
the EU and/or elsewhere. All rights reserved.
© 2008-2015 Freescale Semiconductor, Inc.

Getting Started with Freescale MQX™and IAR Embedded Workbench®, Rev. 5, 04/2015
Freescale Semiconductor 1
Table of Contents
Getting Started with Freescale MQX™ RTOS and IAR Embedded Workbench®........................i
1 Read Me First...............................................................................................................................2
2 Building the MQX RTOS Libraries and example application ....................................................3
2.1 Batch Build in IAR Embedded Workbench IDE........................................................................3
2.2 Build example/demo application project file.............................................................................4
3 Running and Debugging the MQX RTOS application................................................................5
3.1 Run MQX RTOS Hello World program....................................................................................5
3.2 Multi-core debugging...............................................................................................................6
3.3 Debugging (attach) the Application loaded by MQX RTOS Bootloader..................................11
3.4 MQX RTOS Task Aware Debugging .....................................................................................13
4 Using the MQX RTOS DebugI/O Driver with EWARM IDE.......................................................19

Getting Started with Freescale MQX™and IAR Embedded Workbench®, Rev. 5, 04/2015
Freescale Semiconductor 2
1 Read Me First
This document describes the 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. See Getting Started with Freescale MQX™RTOS and other user documentation
included within the latest Freescale MQX RTOS installation for more details not specifically related
to the IAR Embedded Workbench tools.
Get the latest Freescale MQX RTOS at freescale.com/mqx.

Getting Started with Freescale MQX™and IAR Embedded Workbench®, Rev. 5, 04/2015
Freescale Semiconductor 3
2 Building the MQX RTOS Libraries and example application
See Chapter 2 of the Getting Started with Freescale MQX™ RTOS (document MQXGSRTOS) for
details on generic build process and compile time configuration. This document concentrates on
steps specific to IAR tool chain only.
For MQX RTOS v4.2.0, each example/demo application comes with one workspace file, which
contains the path to the example/demo project file and all dependent MQX RTOS library project
files. Import the workspace file in the folder. For example, with MQX RTOS:
<mqx_install_dir>/mqx/examples/<example>/build/iar/<example>_<board_name>/<exampl
e>_<board_name>.eww
For Hello World example of MQX RTOS for FRDMK64F120M, the workspace file is located in
folder:
<mqx_install_dir>/mqx/examples/hello/build/iar/hello_frdmk64f/hello_frdmk64f.eww
Figure 1- Import projects into IAR workspace
2.1 Batch Build in IAR Embedded Workbench IDE
The IAR IDE supports build of multiple project files in one go. Follow these spets to build all the
MQX RTOS library project files within a workspace at once.
Go to menu “Project / Batch Build” or press the F8 key in the IAR IDE.
Select Batch configuration to build (see next section for more details about build targets).
Press the “Make” button to start the batch build process.

Getting Started with Freescale MQX™and IAR Embedded Workbench®, Rev. 5, 04/2015
Freescale Semiconductor 4
Figure 2- Batch build
2.2 Build example/demo application project file
Select the build target and memory configuration for the example/demo application. With the
Hello World example application of MQX RTOS for FRDMK64120M, it is Int Flash
Debug/Int Flash Release
Figure 3- Build application
Go to menu Project/Make, press the F7 key, or click the icon in the IAR IDE to build the
application.

Getting Started with Freescale MQX™and IAR Embedded Workbench®, Rev. 5, 04/2015
Freescale Semiconductor 5
3 Running and Debugging the MQX RTOS application
The description bellow is provided for FRDMK64F120M BSP and Hello World example application.
The same procedure applies for all other BSPs and examples.
3.1 Run MQX RTOS Hello World program
Loading and debugging MQX RTOS applications is an easy task with IAR Embedded Workbench
tool and it is not different from debugging classic non-OS applications. Make sure that you select
the correct debugger interface in the project options and that you use the correct processor
initialization Macro file.
Connect the USB cable to the OpenJTAG connector on TWR-K60N512 board. Open the
Terminal Window application by using Port USB COM, Baud 115200, Parity None, Bits 8.
In project/Options-Debugger check debugger Driver settings. Default is J-Link. When a MQX
RTOS application is compiled and linked to all MQX RTOS libraries, press the debug button
to download the application to target.
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.
Therefore, the use of TAD plugin features, as described in subsequent sections, is limited.
Figure 4- mqx_main.c
Press the “Run” button to start the application.
Figure 5- Run button
Hello World is printed on serial console terminal.
Figure 6 –Console terminal

Getting Started with Freescale MQX™and IAR Embedded Workbench®, Rev. 5, 04/2015
Freescale Semiconductor 6
3.2 Multi-core debugging
This chapter describes the basics of multi-core debugging with MQX RTOS. Description is provided
for twrvf65gs10_a5 a twrvf65gs10_m4 (Vybrid) board support package and MCC (multi-core
communication) example application. In this case, the ARM® Cortex®-A5 is the primary core while
the ARM® Cortex®-M4 is set up as an auxiliary core.
3.2.1 Debugging with J-Link
Before you start, ensure that the IAR 6.50.2 or newer and the latest J-Link drivers from
SEGGER is used.
Open two instances of IAR IDE. In the first IDE instance, open the Cortex-A5 example
application. In the second IDE instance, open the application for Cortex-M4 core.
<mqx_install_dir>/mcc/examples/pingpong/build/iar/pingpong_example_twrvf65gs10
_a5
And
<mqx_install_dir>/mcc/examples/pingpong/build/iar/pingpong_example_twrvf65gs10
_m4
Ensure that both MQX RTOS library and MCC (<mqx_install_dir>/mcc/build) library are
compiled for each core prior to the compilation of the example application. Set the following
parameters before debugging:
For primary core (Cortex-A5), set in project Options:

Getting Started with Freescale MQX™and IAR Embedded Workbench®, Rev. 5, 04/2015
Freescale Semiconductor 7
Figure 7- Options
Set “JTAG scan chain with multiple targets” and TAP number “0” in the J-Link/J-Trace
setting.
Figure 8-Options for node
For secondary core, select “JTAG scan chain with multiple targets” and TAP number “3” in
the J-Link/J-Trace setting. The number 0 and 3 are the indexes of the CPUs on JTAG chain.
Since this can differ on other processors, see your processor Reference Manual for details.

Getting Started with Freescale MQX™and IAR Embedded Workbench®, Rev. 5, 04/2015
Freescale Semiconductor 8
Figure 9- Options for node
Set the Reset type to “Core.”
Figure 10- Options for node - setup
Start the primary core (Cortex-A5) application . You should see the following message on
the terminal:
Figure 11- Terminal
Start the auxiliary core (Cortex-M4) application . The responder starts and the message
“pingpong” starts between the cores.

Getting Started with Freescale MQX™and IAR Embedded Workbench®, Rev. 5, 04/2015
Freescale Semiconductor 9
Figure 12- Terminal
3.2.2 Debugging with I-Jet
Debugging the multicore with I-Jet probe does not offer a possibility to run two debug instances at
once. Only one core can be under the debugger at any one time. Special settings are needed to
change this. See the steps bellow:
First, the debugger needs to switch to I-Jet got you I-Jet/JTAGjet menu and update
Firmware in EmuDialog Menu.

Getting Started with Freescale MQX™and IAR Embedded Workbench®, Rev. 5, 04/2015
Freescale Semiconductor 10
Figure 13- I-Jet
Choose "arm\bin\jet\firmware\i-jet\v2\I-JET.upg"
The frequency needs to be set to 1 Mhz. The autodetect does not work correctly. This will be
solved in future IAR versions.

Getting Started with Freescale MQX™and IAR Embedded Workbench®, Rev. 5, 04/2015
Freescale Semiconductor 11
Figure 14- Factory settings
Change the interface from JTAG to SWD
3.3 Debugging (attach) the Application loaded by MQX RTOS Bootloader
This chapter describes debugging of the application loaded to the processor memory by MQX
RTOS Bootloader. The similar approach can be used for debugging an application loaded by a
different bootloader e.g., U-Boot. This chapter also briefly describes the steps required for preparing
bootable SD Card image and application images in IAR tool set. For detailed information on Vybrid
Bootloader usage, see Readme.txt located in the MQX RTOS Bootloader application folder.
(<mqx_install_dir>/mqx/examples/bootloader_vybrid/Readme.txt)
Building Bootloader and creating bootable SD card
Import the MQX RTOS Bootloader project to your workspace by using Project/Add Existing
Project menu.
Select the bootloader_vybrid from your MQX RTOS installation directory.
<mqx_install_dir>/mqx/examples/bootloader_vybrid/build/iar/bootloader_vybrid_twrv
f65gs10_a5
Select Int Ram Debug target and compile the application using Project/Make menu.
Follow <mqx_install_dir>/mqx/examples/bootloader_vybrid/Readme.txt description
and use prepare binary image to prepare bootable SD Card.
Building and Debugging the Application images
Build the applications you want to run on A5 and M4 cores the usual way.
Store the binary images to root directory on bootable SD card.

Getting Started with Freescale MQX™and IAR Embedded Workbench®, Rev. 5, 04/2015
Freescale Semiconductor 12
Copy setup.ini to the SD Card and modify according to Readme.txt description.
Remove the SD Card from the PC and plug it into Micro SD Card slot on your Vybrid board.
Power up the Vybrid board. MQX RTOS Bootloader prints out the following message on
default console (RS232 TWR-SER) and start execution of M4 and A5 applications. The
pingpong example image files are copied to the root directory on the bootable SD card.
Figure 15 –Terminal
To debug the running application, go to project properties and setup J-Link/J-Trace settings
as described in the previous chapter.
Go to Debugger menu and uncheck Run to main option.
Figure 16- Debugger menu
Select Attach to running target.

Getting Started with Freescale MQX™and IAR Embedded Workbench®, Rev. 5, 04/2015
Freescale Semiconductor 13
Figure 17- Download
Use the Debug without downloading button . The debugger connects to the
selected application. Stop the selected core and debug the booted image.
3.4 MQX RTOS Task Aware Debugging
MQX RTOS 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 RTOS data
structures, task-specific information, I/O device drivers, and other MQX RTOS context data.
3.4.1 Installing IAR Embedded Workbench TAD
TAD plug-in DLL is pre-installed in IAR Embedded Workbench automatically. To update the plug-in
to a new version included with the latest MQX RTOS installation, perform the following manual
installation steps:
Close the IAR Embedded Workbench IDE.
Locate the tools\iar_extensions\<platform>directory in Freescale MQX RTOS
installation folder (by default C:\Freescale\Freescale MQX x.y).
Copy the entire content of tools\iar_extensions\<platform>directory to the IAR
Embedded Workbench installation folder (e.g.,
C:\Program Files\IAR Systems\Embedded Workbench 6.4\arm)
After the steps above are done, verify that the TAD plugin files exist at the new location:
<EW>\<platform>\plugins\rtos\MQX\MQXRtosPlugin.ewplugin
<EW>\<platform>\plugins\rtos\MQX\MQXRtosPlugin<PLATFORM>.dll"
Re-start IAR Embedded Workbench IDE.
In the Embedded Workbench environment, you should now be able to enable MQX RTOS
TAD by selecting “MQX RTOS”in the “Plugins” tab of the “Debugger” panel of project
settings. All example applications included with Freescale MQX RTOS are already
configured this way.

Getting Started with Freescale MQX™and IAR Embedded Workbench®, Rev. 5, 04/2015
Freescale Semiconductor 14
Figure 18-Plugins

Getting Started with Freescale MQX™and IAR Embedded Workbench®, Rev. 5, 04/2015
Freescale Semiconductor 15
3.4.2 Using MQX RTOS TAD Screens
Using the MQX RTOS or RTCS menu in IAR IDE main window, several TAD “screens” may be
opened during the debugging session.
Figure 19- MQX RTOS TAD screens
The most helpful and frequently used screens are shown in the images below:
Task Summary –overview about all tasks created in the MQX RTOS application.
Figure 20- Task summary

Getting Started with Freescale MQX™and IAR Embedded Workbench®, Rev. 5, 04/2015
Freescale Semiconductor 16
Stack Usage Summary –displays information about interrupt and task stacks. Typically, a
stack overflow is a root cause for vast majority of problems in MQX RTOS user applications.
Figure 21 –Stack usage summary
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 RTOS system or applications. Additional memory pools (if used) may be displayed by
using the “Memory Pools” screen.
Figure 22- Memory block summary
Semaphores, Events (or Lightweight Semaphores, Lightweight Events) –displays address
and status of synchronization objects created by the MQX RTOS system or application.
When a synchronization object is allocated either as a global or static variable in the system,
or 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™and IAR Embedded Workbench®, Rev. 5, 04/2015
Freescale Semiconductor 17
Figure 23- Lightweight semaphore summary

Getting Started with Freescale MQX™and IAR Embedded Workbench®, Rev. 5, 04/2015
Freescale Semiconductor 18
3.4.3 Task-aware Debugging
The TAD plug-in also provides native debugger support for multi-tasking MQX RTOS 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 RTOS menu, in the IAR IDE main window, select the “Task List” item at the top of the
menu. The Task List view opens at the top of the window and gives 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.
Figure 24- IAR