RTX MiniTutorial
DEBUGGING APPLICATIONS USING
VISUAL STUDIO
Copyright © 1996-2013 by IntervalZero, Inc. All rights reserved.
No part of this document may be reproduced or transmitted in any form or by any means, graphic, electronic, or mechanical, including
photocopying, and recording or by any information storage or retrieval system without the prior written permission of IntervalZero, Inc.
unless such copying is expressly permitted by federal copyright law.
While every effort has been made to ensure the accuracy and completeness of all information in this document, IntervalZero, Inc.
assumes no liability to any party for any loss or damage caused by errors or omissions or by statements of any kind in this document,
its updates, supplements, or special editions, whether such errors, omissions, or statements result from negligence, accident, or any
other cause. IntervalZero, Inc. further assumes no liability arising out of the application or use of any product or system described
herein; nor any liability for incidental or consequential damages arising from the use of this document. IntervalZero, Inc. disclaims all
warranties regarding the information contained herein, whether expressed, implied or statutory, including implied warranties of
merchantability or fitness for a particular purpose.
IntervalZero, Inc. reserves the right to make changes to this document or to the products described herein without further notice.
Microsoft, MS, and Win32 are registered trademarks and Windows 7, Windows Vista, Windows XP, and Windows Server 2003 are
trademarks of Microsoft Corporation.
All other companies and product names may be trademarks or registered trademarks of their respective holders.
MiniTutorial: Debugging Applications Using Visual Studio
IZ-DOC-X86-0056
April 2015
400 Fifth Avenue
www.intervalzero.com
Fourth Floor
Waltham, MA 02451
Phone: 781-996-4481
Overview
IntervalZero RTX applications can be debugged using the familiar Microsoft Visual Studio development
environment. This MiniTutorial will show how to debug:
l
A simple application
l
An application using an RTDLL function library
To ensure you are running in a supported environment, please read the section Preparing your RTX
Environment in the product documentation.
This MiniTutorial corresponds with RTX 2012.
Running an RTSS Application in the Debugger
When Real-time Subsystem (RTSS) applications are debugged in the Visual Studio development
environment, the RTX debugger add-in ensures that the RTSS project will be under RTX control. RTSS
applications are started by the RTX loader instead of the Windows loader. For this reason, when debugging
RTSS applications in Visual Studio, conditional breakpoints and the following options in the Debug pulldown menu (which would assume Windows control) are not supported:
l
Start without debugging
l
Attach to Process
l
Detach All
Sample Programs
Program source code that will be used in debug examples will come from existing applications found in the
RTX samples directory. The default location for the RTX samples is:
C:\ProgramData\RTX\samples
The Visual Studio 2010 Development Environment was used for the debug examples.
Real-Time Subsystem
Before running or debugging any of the programs, ensure that the real-time subsystem is up by checking
the Control tab in the RTX properties control panel.
IZ-DOC-X86-0056
1
Overview
Simple Visual Studio Debug Session
The following steps will demonstrate a simple Visual Studio debug session, using one of the provided RTX
sample programs. Follow along to:
l
Start Visual Studio and create a new project
l
Build the project
l
Perform simple debugging
Start Visual Studio and Create a New Project
Steps:
1. To begin your debug session, start Microsoft Visual Studio.
2. To check if the add-in has successfully been installed, select Add-in Manager from the Tools pull-down
menu and look for RTX Debugger Support (with a check in the box to the left) in the list of available
add-ins. Or, look for the RTX toolbar:
3. Start a new project by clicking File > New > Project
IZ-DOC-X86-0056
2
Simple Visual Studio Debug Session
4. When the New Project wizard begins, select Rtx Application from the Visual C++ templates, name the
project RtxRespTime and select a location to store project files.
NOTE: The difference between the Rtx Application Wizard and Driver Wizard is the source
template that will be provided.
The RTX Application Wizard overview shows the initial default settings. To modify these defaults, click
Next.
IZ-DOC-X86-0056
3
Simple Visual Studio Debug Session
5. Select Multithreaded C Run-time support to allow your application to make supported C Runtime
calls and then click Finish.
NOTE: Clicking Next will allow you to create a basic application framework, which is not
necessary since existing sample programs will be used.
This session will use the existing System Response Time Measurement (SRTM) program found in the
RTX samples directory.
IZ-DOC-X86-0056
4
Simple Visual Studio Debug Session
6. Copy the Srtm.c source code file to the directory that was just created for the project RtxRespTime.
The files now in the project directory should look something like this:
7. Add the Srtm.c program to your project by right-clicking Source Files and selecting Add → Existing
Item... from the pull-down menu.
8. Browse to your new project directory, select the sample program that you recently copied there and
click Add.
IZ-DOC-X86-0056
5
Simple Visual Studio Debug Session
Build the Project
When the RTX Application Wizard runs, it creates solution configurations to build Win32 executable files
with and without debug symbols (Debug / Release) and RTSS executable files with and without debug
symbols (RTSSDebug / RTSSRelease). These solution configurations can be see in the pull-down menu.
Steps:
1. To build all executable files at once, select Batch Build... from the Build pull-down menu.
IZ-DOC-X86-0056
6
Simple Visual Studio Debug Session
2. Select the boxes to the right of each solution configuration and then click Build or Rebuild.
Build output will display in the Output window at the bottom of the screen. If the output window is not
visible, select Output from the View pull-down menu.
------ Build started: Project: RtxRespTime, Configuration: RTSSRelease Win32
-----Srtm.c
RtxRespTime.vcxproj -> C:\Program
Files\IntervalZero\RTX\samples\RtxRespTime\RTSSRelease\RtxRespTime.rtss
StampTool: Successfully stamped file 'C:\Program
Files\IntervalZero\RTX\samples\RtxRespTime\RTSSRelease\RtxRespTime.rtss'!
------ Build started: Project: RtxRespTime, Configuration: RTSSDebug Win32 ----Srtm.c
RtxRespTime.vcxproj -> C:\Program
Files\IntervalZero\RTX\samples\RtxRespTime\RTSSDebug\RtxRespTime.rtss
StampTool: Successfully stamped file 'C:\Program
Files\IntervalZero\RTX\samples\RtxRespTime\RTSSDebug\RtxRespTime.rtss'!
------ Build started: Project: RtxRespTime, Configuration: Release Win32 ----Srtm.c
RtxRespTime.vcxproj -> C:\Program
Files\IntervalZero\RTX\samples\RtxRespTime\Release\RtxRespTime.exe
------ Build started: Project: RtxRespTime, Configuration: Debug Win32 ----Srtm.c
IZ-DOC-X86-0056
7
Simple Visual Studio Debug Session
RtxRespTime.vcxproj -> C:\Program
Files\IntervalZero\RTX\samples\RtxRespTime\Debug\RtxRespTime.exe
========== Build: 4 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========
Perform Simple Debug
Steps:
1. Open the source file that you will be debugging by right-clicking the file name and selecting Open from
the pull-down menu, or by double-clicking the file name.
2. Set the first breakpoint by double-clicking in the column to the left of the RtCreateTimer function
call, or by right-clicking on the line and clicking Breakpoint > Insert Breakpoint in the pop-up menu.
IZ-DOC-X86-0056
8
Simple Visual Studio Debug Session
3. Set a second breakpoint by double-clicking in the column to the left of the RtGetClockTime function
call.
4. Select one of the available Solution Configurations from the short-cut menu, or by selecting
Configuration Manager from the Build pull-down menu. To debug the Win32 version of the program,
set the solution configuration to Debug. To debug the RTSS version of the program, set the solution
configuration to RTSSDebug.
IZ-DOC-X86-0056
9
Simple Visual Studio Debug Session
5. To start debugging, select Start Debugging from the Debug pull-down menu, or press the F5 key.
6. The RTX Server console window will open and display text from the program and then the debugger
will stop the program at the first breakpoint.
7. To continue from the breakpoint, select Continue from the Debug pull-down menu or press the F5 key.
IZ-DOC-X86-0056
10
Simple Visual Studio Debug Session
8. When the debugger stops at the second breakpoint, view variable values in the Autos window. If the
debug windows are not visible, use the Windows option in the Debug pull-down menu to display
them. Press the F5 key to continue debugging.
9. While debugging, you can select to Continue or to Stop Debugging from the Debug pull-down menu.
If you select Continue, program execution will continue until it completes or reaches another
breakpoint. If you select Stop, program execution will halt.
After you have finished the debug session, you can close the RTX Server console window.
IZ-DOC-X86-0056
11
Simple Visual Studio Debug Session
Visual Studio Debug of RTDLL
The following steps will demonstrate a simple Visual Studio debug session, when the application uses an
RTDLL. An RTDLL is not an RTSS process, so it can be debugged within the Visual Studio instance that is
debugging your application.
This solution will use existing projects from samples directory (listed in the Overview at the start of this
document).
To debug an RTX application and an RTDLL, do the following:
l
Start Visual Studio and Create an Empty Solution
l
Add Projects to the Solution
l
Build Projects in the Solution
l
Register the RTDLL
l
Debug the Program and RTDLL
Start Visual Studio and Create a New Solution
Begin the debug session:
1. Start Microsoft Visual Studio and create a new project using: File > New > Project
IZ-DOC-X86-0056
12
Visual Studio Debug of RTDLL
2. When the New Project window appears, expand Other Project Types, click Visual Studio Solutions
and then select Blank Solution. Name the project RtxApp_wRTDLL, specify the location that you will
store project files and then click OK.
3. You should now have a blank solution called RtxApp_wRtDll. Begin creating a new project that will
contain the RTDLL by right-clicking the solution name and selecting Add > New Project
IZ-DOC-X86-0056
13
Visual Studio Debug of RTDLL
4. In the Add New Project window, select the Visual C++ > Rtx Application template. Give the project a
name, ensure it uses the same directory as the solution and then click OK.
5. Click Next in the Welcome window.
IZ-DOC-X86-0056
14
Visual Studio Debug of RTDLL
6. To build an RTDLL, select RTX DLL, add C Runtime support and then click Finish.
7. Locate the sample program sampleRtdll.c.
IZ-DOC-X86-0056
15
Visual Studio Debug of RTDLL
8. Copy the sampleRtdll.c program to the new RTDLL project directory.
9. Return to Visual Studio and add the sample program by right-clicking the SampleRtDll project Source
Files and selecting Add > Existing Item from the pull-down menu.
10. Browse to the SampleRtDll project directory, select the sampleRtdll.c program and click Add.
Create a new application to use the DLL
1. Right-click the RtxApp_wRtDll solution name and selecting Add > New Project from the pull-down
menu.
IZ-DOC-X86-0056
16
Visual Studio Debug of RTDLL
2. Select the Visual C++ > Rtx Application template, name the new project UsingRtDll, ensure it is
using the same directory as your solution and then click OK.
3. In the RTX Application Wizard Welcome window, click Next.
4. In the RTX Application Wizard Application Settings window, select RTX application and C Runtime
support and then click Finish.
IZ-DOC-X86-0056
17
Visual Studio Debug of RTDLL
5. Locate the usingRtdll.c program in the RTX samples directory.
6. Copy the usingRtdll.c program to your new project directory.
7. Return to Visual Studio and add the sample program by right-clicking the UsingRtDll project Source
Files and selecting Add > Existing Item from the pull-down menu.
8. Browse to the UsingRtDll project directory, select the usingRtdll.c program and click Add.
You should now have a solution with the two projects you created. The SampleRtDll project will create
an RTDLL and the UsingRtDll project will use the RTDLL.
IZ-DOC-X86-0056
18
Visual Studio Debug of RTDLL
Program and DLL Interaction
The sample DLL can be built to run under Windows or RTX. When the DLL is built as a Win32 library, it will
have a .DLL file extension. When it is built to run in the real-time subsystem, it will have a .RTDLL file
extension. The program UsingRTDLL.c source file currently lists sampleRTDLL.dll (with the .dll
extension) in its call to LoadLibrary. This is correct for all configurations, as the RTX Loadlibrary function call
will load the correct dynamic library (DLL or RTDLL) based on the calling application Windows (exe) or Realtime ( RTSS).
When the solution is built, the program that will use the DLL should startup when debugging begins. Ensure
this is the case by right-clicking the UsingRtDll project and selecting Set as StartUp Project from the pulldown menu.
IZ-DOC-X86-0056
19
Visual Studio Debug of RTDLL
Build the Solution
When the projects were created using the RTX wizards, four solution configurations were defined for each
project. They allow the creation of Win32 executable files with, and without debug symbols (Debug /
Release) and RTSS executable files with, and without debug symbols (RTSSDebug / RTSSRelease).
Steps:
1. To select which configuration will be built, select Batch Build from the Build pull-down menu.
IZ-DOC-X86-0056
20
Visual Studio Debug of RTDLL
2. This tutorial will only use the RTSSDebug configurations. You can check only SampleRtDll RTSSDebug
configuration and UsingRtDll RTSSDebug configuration, or select all configurations. After
configuration options have been selected, click Build or Rebuild.
3. Output from the build will be displayed in the debugger Output window.
The solution directory will now have executable files for each of the projects.
IZ-DOC-X86-0056
21
Visual Studio Debug of RTDLL
Register the RTDLL
Each time a new RTDLL is built (or changed) it must be registered. Register the RTDLL using the RtssRun
command or by starting the program.
Steps:
1. Launch RtssRun: IntervalZero > RTX 2012 > Tools > RtssRun
2. Browse to the location of the RTDLL that was just created, click the Register RTDLL radio button and
then click OK.
IZ-DOC-X86-0056
22
Visual Studio Debug of RTDLL
3. To verify that the RTDLL was registered, look for SampleRTDLL.RTDLL in the RTSS Task Manager by
starting the program: IntervalZero > RTX 2012 > Tools > RTSS Task Manager
Perform Debug of Program and RTDLL
To debug the program and RTDLL, ensure that the configuration is set to RTSSDebug.
Steps:
1. Set the first breakpoint in program UsingRTDLL.c by double-clicking in the column to the left of the
RtCreateTimer function call or by right-clicking on the line and clicking Breakpoint > Insert
Breakpoint in the pop-up menu.
IZ-DOC-X86-0056
23
Visual Studio Debug of RTDLL
2. Set a second breakpoint in program UsingRTDLL.c by double-clicking in the column to the left of the
call to function toggle (pointed to by FunctionPtr). This function is located in the RTDLL.
3. To start debugging, select Start Debugging from the Debug pull-down menu, or press the F5 key.
IZ-DOC-X86-0056
24
Visual Studio Debug of RTDLL
4. If you get a message asking if you would like to rebuild the SampleRTDLL click No. A rebuild is not
necessary since there were no changes since the previous build.
5. The debugger will stop at the first breakpoint, pointed to by a yellow arrow in a red circle.
IZ-DOC-X86-0056
25
Visual Studio Debug of RTDLL
6. At the first breakpoint, click Modules at the bottom of the window. If symbols are not loaded for either
of the modules, right-click and select Load Symbols from the pull-down menu.
NOTE: If Modules is not available from the status bar at the bottom of the window, select
Modules from the Windows option in the Debug pull-down menu to open the modules
window.
IMPORTANT! Visual Studio 2008 SP1 does not always load RTDLL symbols correctly. This is a
known issue for RTX.
7. If necessary, locate the symbol file in the RTSSDebug subdirectory.
The Output window should now indicate that symbols are loaded.
8. To continue from the first breakpoint, select Continue from the Debug pull-down menu or press the F5
key.
9. When the debugger stops at the second breakpoint, if this is the call to the toggle function, select Step
Into or press the F11 key to step into the DLL function.
Focus will now turn to the SampleRTDLL.c source code.
IZ-DOC-X86-0056
26
Visual Studio Debug of RTDLL
10. To continue, select Step Out from the Debug pull-down menu or press Shift+F11.
When focus returns to the SampleRTDLL.c program, you can select to Continue or to Stop
Debugging from the Debug pull-down menu. If you select Continue, program execution will continue
until it completes or reaches another breakpoint. If you select Stop, program execution will halt.
IZ-DOC-X86-0056
27
Visual Studio Debug of RTDLL
Resources
For more information, visit the IntervalZero website at http://www.intervalzero.com/.
IZ-DOC-X86-0056
28
Resources