rtx quick start guide - intervalzero · pi_rtss.lib rtx_rtss.lib link : warning lnk4010: invalid...
TRANSCRIPT
IntervalZero Quick Start Guide
for RTX 2011
Copyright © 1996-2011 by IntervalZero, Inc. All rights reserved.
No part of this document may be reproduced or transmitted in any form or by any means, graphic, elec-tronic, or mechanical, including photocopying, and recording or by any information storage or retrieval sys-tem without the prior written permission of IntervalZero, Inc. unless such copying is expressly permitted byfederal copyright law.
While every effort has been made to ensure the accuracy and completeness of all information in this doc-ument, IntervalZero, Inc. assumes no liability to any party for any loss or damage caused by errors or omis-sions or by statements of any kind in this document, its updates, supplements, or special editions, whethersuch 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 describedherein; nor any liability for incidental or consequential damages arising from the use of this document. Inter-valZero, 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 hereinwithout further notice.
IntervalZero RTX® is a registered trademark of IntervalZero, Inc.
Microsoft, MS, and Win32 are registered trademarks and Windows 7, Windows Vista, Windows Server2003 and Windows XP are trademarks of Microsoft Corporation.
All other companies and product names may be trademarks or registered trademarks of their respectiveholders.
IntervalZero Quick Start Guide for RTX 2011
Document Number DOC-RTX-1000-010
January 2011
Contents
Contents
Contents 31.0 Introduction 51.1 Preparing Your RTX Environment 51.2 Development Host Requirements 61.3 Software Prerequisites 6
2.0 Running RTSS Tasks 62.0 Create a Visual Studio Project for Existing Code 72.1 Start a New Visual Studio Project 72.2 Add an Existing Program to the Project 92.3 Build and Run the Program 11
3.0 Run Program from Visual Studio 123.1 Use Visual Studio Start Debugging Button 123.2 Use the Debug Pull-Down Menu to Start Without Debugging 13
4.0 Create a New Visual Studio Project 174.1 Start a New Visual Studio Project 174.2 Select an Application Template. 174.3 Modify the Program 214.4 Build and Run an RTX Executable 234.5 Build and Run a Windows Executable 25
5.0 Prepare to Build from the Command Prompt 275.1 The Master Make File 275.2 Makefile Variables 28
6.0 Build a Program from the Command Prompt 286.1 Copy and Build a Sample Program 286.2 Execute the Sample as a Win32 Process 306.3 Execute the Sample as an RTSS Process 31
- 3 -
1.0 Introduction
1.0 Introduction
Welcome to the IntervalZero RTX 2011 Software Development Kit (SDK); a real-time extension for Microsoft Windows. RTX enhances Windows by providing hardreal-time and control capabilities to a general purpose operating system that isfamiliar to developers and their end users.
Use this guide to start using the various components of the RTX Runtime andSDK.
1.1 Preparing Your RTX EnvironmentThis QuickStart guide assumes that you have already read the IntervalZeroRTX® Release Notes and, following the instructions in the IntervalZero RTX®Installation Guide:
l Verified that your system meets the hardware and software requirements
l Installed a supported Visual Studio suite before installing the RTX SDK
l Installed IntervalZero's RTX SDK
The RTX software can be installed by:
l Requesting an evaluation version from http://www.intervalzero.com/rtx.htmand then using instructions from the Installation Guide that came with yourevaluation software
l Downloading a purchased version from http://www.intervalzero.com/rtx_pur-chased.htm and then using instructions from the Installation Guide thatcame with your purchased software
l Requesting a Product CD and using the instructions from the InstallationGuide that came with your purchased software
The RTX Installation will add:
l The RTX Runtime, used to manage RTX executable code
l Libraries and header files used to build RTSS applications
l Add-ins to support development and debugging with Visual Studio
l Tools to monitor and profile the subsystem and your RTSS application
- 5 -
If you have not completed these tasks, please do so before trying the examplespresented in this Quick Start Guide.
1.2 Development Host RequirementsTo use RTX 2011, you must have a system with one of the following operatingsystems:
l Windows 7
l Windows Vista
l Windows XP Professional
l Windows Server 2003
Note: See the Installation Guide for your software kit for more details on each ofthese host system requirements.
1.3 Software PrerequisitesThe RTX 2011 SDK requires that you have Microsoft Visual Studio 2010, VisualStudio 2008 or Visual Studio 2005 installed if you wish to debug RTX programswith the Visual Studio IDE.
Note: To verify that your system is configured for RTX development in the VisualStudio environment, start Visual Studio and ensure that the RTX toolbar is dis-played. For more information, see the installation guide for your software kit.
2.0 Running RTSS Tasks
RTX Applications are controlled by the Real-Time Subsystem (RTSS) Task Man-ager.
You can view running RTX applications by clicking All Programs and selecting
IntervalZero > RTX 2011 > Tools > RTSS Task Manager
While the RTSS Task Manager is running, start the RTX demo program by click-ing:
All Programs > IntervalZero > RTX 2011 > Tools > RtxDemo
- 6 -
2.0 Create a Visual Studio Project for Existing Code
2.0 Create a Visual Studio Project for ExistingCode
To demonstrate using Visual Studio with RTX, you can start by building one ofthe sample programs.
2.1 Start a New Visual Studio ProjectStart Visual Studio by selecting it from the Start menu and then create a newproject by clicking New > Project in the File pull-down menu.
Select Rtx Application wizard from the Visual C++ Project types.
Note: Selection of an application wizard instead of a device driver wizard deter-mines the template starting code only. There are no compiler or linker differences.
- 7 -
Give the project a name (for this sample, the project will be called RtxSample1).Select a location to save project files and then click OK.
Confirm use of the default selections by clicking Finish.
- 8 -
2.0 Create a Visual Studio Project for Existing Code
2.2 Add an Existing Program to the ProjectAdd your program file by selecting to Add an Existing Item to the Source Files.
- 9 -
Find the existing program file and add it.
Open the Configuration Manager to view current settings.
- 10 -
2.0 Create a Visual Studio Project for Existing Code
The application wizard provides four solution configurations: Debug, Release,RTSSDebug and RTSSRelease. This allows the same code to be built as eitherWin32 .exe or RTX .rtss executable code.
Set the Active solution configuration to one of the RTSS choices: RTSSDebugor RTSSRelease.
2.3 Build and Run the ProgramSelect Build RtxSample1 or Rebuild RtxSample1 from the Build pull-downmenu to create an .rtss output file.
- 11 -
Run the RTSS application by typing the following from a command prompt.
> RTSSrun <my-sample-dir>/RtxSample1 –h –s –f 10
Where my-sample-dir is the location of your project.
If you do not need to enter parameters, you can also double-click the file name inWindows Explorer.
3.0 Run Program from Visual Studio
There are two ways in which an RTX .rtss executable program can be startedfrom within Visual Studio:
l Use the Start Debugging button after setting solution configuration toRTSSDebug.
l Use the Debug pull-down menu to Start Without Debugging after settingup rtssrun command and arguments.
3.1 Use Visual Studio Start Debugging ButtonTo set up a Visual Studio environment that will allow use of the Start Debuggingbutton, follow the steps below.
- 12 -
3.0 Run Program from Visual Studio
Ensure that RTSSDebug is selected from the Solutions Configurations pull-downmenu.
Click the Start Debugging button, click Debug > Start Debugging or press F5.
3.2 Use the Debug Pull-Down Menu to Start WithoutDebuggingTo set up a Visual Studio environment that will allow use of the Debug pull-downmenu, follow the steps below.
From the Configurations drop-down menu, select RTSSRelease.
- 13 -
From the Projectmenu, choose Properties to open the Property pages dialogbox.
After selecting Debugging from Configuration Properties, enter the full pathname for the rtssrun.exe program and the path to your .rtss image and thenclick OK.
- 14 -
3.0 Run Program from Visual Studio
To start execution from the Debug menu, click Start Without Debugging.
- 15 -
- 16 -
4.0 Create a New Visual Studio Project
4.0 Create a New Visual Studio Project
This section will provide an opportunity to create a new Visual Studio project.
4.1 Start a New Visual Studio ProjectStart Visual Studio by selecting it from the Start menu and then create a newproject by clicking New > Project in the File pull-down menu.
4.2 Select an Application Template.Select the Rtx Application wizard from the Visual C++ Project type templates.
Note: Selection of an application wizard instead of a device driver wizard deter-mines the template starting code only. There are no compiler or linker differences.
- 17 -
Give the project a name (for this sample, the project will be called RtxSample2).Select a location to save project files and then click OK.
- 18 -
4.0 Create a New Visual Studio Project
View current settings and then click Next.
- 19 -
Ensure RTX application is selected in the Application Settings window. In mostcases,Multithreaded C Run-time support should also be included. Click Nextto continue.
- 20 -
4.0 Create a New Visual Studio Project
Select Provide a program framework, select elements for a Periodic timerthread and then click Finish.
4.3 Modify the ProgramOpen the new program shell by selecting it from the list of Source Files.
- 21 -
Increase the timer period from 500 microseconds to 1 second.
Set the test duration to 5 seconds and then display a completion message.
- 22 -
4.0 Create a New Visual Studio Project
Open the RtxSample2Funcsource file and add a line to display status when theTimerHandler is called.
4.4 Build and Run an RTX ExecutableSet the Solution Configuration so that the program will be built as an RTSSRe-lease executable.
Select Build Solution from the Build pull-down menu.
- 23 -
Run the .rtss executable either by double-clicking on the file name in Explorer orby typing into a command prompt:
rtssrun RtxSample2
- 24 -
4.0 Create a New Visual Studio Project
4.5 Build and Run a Windows ExecutableThe sample program can also be built as a Windows executable as describedbelow.
Set the Solution Configuration so that the program will be built as a WindowsDebug executable.
Select Build Solution from the Build pull-down menu.
- 25 -
Run the resulting Windows executable program by double-clicking the file namein Explorer or by typing the full path name into a command prompt.
Run the Windows .exe file from within Visual Studio.
- 26 -
5.0 Prepare to Build from the Command Prompt
5.0 Prepare to Build from the Command Prompt
Most RTX application programs can be built to run as Windows executables(.exe) or as RTX executables (.rtss). To prepare your system to build an rtssexecutable file, follow the steps listed below.
Note: RTX does not register its lib and include directories with the system. If youwill be using nmake to build your application, you must run RtxSetEnv.bat,located in the RTX bin directory, to add RTX directory paths to your current envi-ronment.
Open a Microsoft Visual Studio Tools command prompt from the Start menu byselecting:
Start > Visual Studio > Visual Studio Tools > Visual Studio CommandPrompt
Note: If a Windows command prompt is used, you must first find and execute thefile vcvars or vcvars32 from the installation directory for the version of Visual Stu-dio that will be used to build your application.
Run the rtxsetenv.bat routine to set up the RTX environment.
> <RTX_DIR>/bin/rtxsetenv.bat
Where the default value for RTX_DIR is:
C:/Program Files/IntervalZero/RTX.
For example:
C:\>cd "C:\Program Files\IntervalZero\RTX\bin
C:\Program Files\IntervalZero\RTX\bin>rtxsetenv.bat
Setting environment for using IntervalZero RTX.
5.1 The Master Make FileSetting up the command prompt environment will ensure that the master make fileC:\Program Files\IntervalZero\RTX\include\Rtx.mak will befound. The RTX master makefile is used by the sample program makefiles toproduce both a windows .exe file and and RTX .rtss file.
- 27 -
Rtx.mak contains rules to compile C files and link the resulting objects. You canspecify Win32 executable (.exe) files in a makefile using rtx.mak becausertx.mak includes win32.mak. A Makefile Sample is available in the RTXExample Reference manual.
5.2 Makefile VariablesThe RTX master makefile uses the following variables:
NODEBUG: Specifies that no debugging information is included in the executableimage.
RTSS_MTCRT: Links RTSS multi-threaded applications with the C run-timelibrary.
VISUALSTUDIO=X where the value of X indicates the version of Visual Studio
8 for Visual Studio 2005
90 for Visual Studio 2008
100 for Visual Studio 2010
The default value for VISUALSTUDIO is 100, to support Visual Studio 2010.
Note: If you are performing the examples in this Quick Start Guide, keep the com-mand prompt window open to perform additional tasks described throughout thisguide.
6.0 Build a Program from the Command Prompt
To build one of the RTX sample programs, follow the steps listed below.
6.1 Copy and Build a Sample ProgramCreate a working directory. This sample will use C:\S-amples\RTX\RtxSampleSrtm.
Copy the RTX SRTM sample program directory to your working directory
from: <RtxSamples>\samples\srtm
to: C:\Samples\RTX\RtxSampleSrtm
- 28 -
6.0 Build a Program from the Command Prompt
Where the default value for <RtxSamples> is
%ALLUSERSPROFILE%\RTX\samples or C:\P-rogramData\RTX\samples
From the Visual Studio Command prompt window, change to your working direc-tory that contains the srtm sample program and make file.
> cd C:\Samples\RTX\RtxSampleSrtm
View the srtm.mak file.
NODEBUG = 1
VISUALSTUDIO = 100
!include <rtx.mak>
all: srtm.rtss srtm.exe
clean:
-del srtm.obj srtm.exe srtm.rtss
Note that it includes the file rtx.mak, located in the directory:
C:\Program Files\IntervalZero\RTX\include\
The srtm.mak file causes the SRTM program to be built as both an RTSS proc-ess (file name srtm.rtss) and a Win32 process (file named srtm.exe).
C:\Samples\RTX\RtxSampleSrtm>nmake -f srtm.mak
Microsoft (R) Program Maintenance Utility Version
10.00.30319.01
Copyright (C) Microsoft Corporation. All rights
reserved.
cl -c -DCRTAPI1=_cdecl -DCRTAPI2=_cdecl -nologo -
GS -D_X86_=1 -DWIN32 -
D_WIN32 -W3 -D_WINNT -D_WIN32_WINNT=0x0500 -DNTDDI_VER-
SION=0x05000000 -D_WIN32_I
E=0x0500 -DWINVER=0x0500 -fp:fast -Ox -DNDEBUG -D_MT -MT
/c srtm.c
srtm.c
link -out:srtm.rtss /NODEFAULTLIB /INCREMENTAL:NO
- 29 -
/NOLOGO -driver -alig
n:0x20 -subsystem:native,4.00 -entry:_RtapiProcessEntry@8
/RELEASE srtm.obj rta
pi_rtss.lib rtx_rtss.lib
LINK : warning LNK4010: invalid subsystem version number
4.00; default subsystem
version assumed
link -out:srtm.exe /INCREMENTAL:NO /NOLOGO -sub-
system:console,5.0 /RELE
ASE srtm.obj rtapi_w32.lib kernel32.lib ws2_32.lib
mswsock.lib advapi32.lib
C:\Samples\RTX\RtxSampleSrtm>
6.2 Execute the Sample as a Win32 ProcessExecute SRTM as a Win32 process using: srtm -h -s -f 10
Where:
-h : Display histogram (in addition to summary).
-s : Turn on sound (square wave driven by timer).
-1 : Use a 10 ms timer period (default is 1 ms).
-f : Use fastest available timer (1 ms or better).
10 : Duration, in seconds, to sample timer latencies
Enter the command as shown below.
> srtm –h –s –f 10
SRTM v2.0 timer delivery latencies for a periodic RTX
timer:
Timer Period = 500 us, Clock Resolution = 0.1 us.
Sample Period = 10 s, Total Ticks = 19977.
Summary:
Minimum = 5 us, Average = 6 us, Maximum = 69 us
Histogram:
0 - 5 us: 0 ***
5 - 6 us: 7
6 - 7 us: 18232
7 - 8 us: 1272
...
60 - 68 us: 0 ***
68 - 69 us: 1
69 - 1000 us: 0 ***
- 30 -
6.0 Build a Program from the Command Prompt
>
6.3 Execute the Sample as an RTSS ProcessTo execute SRTM as an RTSS process, type:
> RTSSrun srtm –h –s –f 10
SRTM v2.0 timer delivery latencies for a periodic RTX
timer:
Timer Period = 500 us, Clock Resolution = 0.1 us.
Sample Period = 10 s, Total Ticks = 19999.
Summary:
Minimum = 1 us, Average = 1 us, Maximum = 4 us
Histogram:
0 - 1 us: 0 ***
1 - 2 us: 19289
2 - 3 us: 689
3 - 4 us: 19
4 - 5 us: 2
5 - 1000 us: 0 ***
- 31 -