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, 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. IntervalZero RTX is a registered trademark of IntervalZero, Inc. Microsoft, MS, and Win32 are registered trademarks and Windows 7, Windows Vista, Windows Server 2003 and Windows XP are trademarks of Microsoft Corporation. All other companies and product names may be trademarks or registered trademarks of their respective holders. IntervalZero Quick Start Guide for RTX 2011 Document Number DOC-RTX-1000-010 January 2011
Contents Contents Contents 3 1.0 Introduction 5 1.1 Preparing Your RTX Environment 5 1.2 Development Host Requirements 6 1.3 Software Prerequisites 6 2.0 Running RTSS Tasks 6 2.0 Create a Visual Studio Project for Existing Code 7 2.1 Start a New Visual Studio Project 7 2.2 Add an Existing Program to the Project 9 2.3 Build and Run the Program 11 3.0 Run Program from Visual Studio 12 3.1 Use Visual Studio Start Debugging Button 12 3.2 Use the Debug Pull-Down Menu to Start Without Debugging 13 4.0 Create a New Visual Studio Project 17 4.1 Start a New Visual Studio Project 17 4.2 Select an Application Template. 17 4.3 Modify the Program 21 4.4 Build and Run an RTX Executable 23 4.5 Build and Run a Windows Executable 25 5.0 Prepare to Build from the Command Prompt 27 5.1 The Master Make File 27 5.2 Makefile Variables 28 6.0 Build a Program from the Command Prompt 28 6.1 Copy and Build a Sample Program 28 6.2 Execute the Sample as a Win32 Process 30 6.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 realtime extension for Microsoft Windows. RTX enhances Windows by providing hard real-time and control capabilities to a general purpose operating system that is familiar to developers and their end users. Use this guide to start using the various components of the RTX Runtime and SDK. 1.1 Preparing Your RTX Environment This QuickStart guide assumes that you have already read the IntervalZero RTX Release Notes and, following the instructions in the IntervalZero RTX Installation Guide: Verified that your system meets the hardware and software requirements Installed a supported Visual Studio suite before installing the RTX SDK Installed IntervalZero's RTX SDK The RTX software can be installed by: Requesting an evaluation version from http://www.intervalzero.com/rtx.htm and then using instructions from the Installation Guide that came with your evaluation software Downloading a purchased version from http://www.intervalzero.com/rtx_purchased.htm and then using instructions from the Installation Guide that came with your purchased software Requesting a Product CD and using the instructions from the Installation Guide that came with your purchased software The RTX Installation will add: The RTX Runtime, used to manage RTX executable code Libraries and header files used to build RTSS applications Add-ins to support development and debugging with Visual Studio 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 examples presented in this Quick Start Guide. 1.2 Development Host Requirements To use RTX 2011, you must have a system with one of the following operating systems: Windows 7 Windows Vista Windows XP Professional Windows Server 2003 Note: See the Installation Guide for your software kit for more details on each of these host system requirements. 1.3 Software Prerequisites The RTX 2011 SDK requires that you have Microsoft Visual Studio 2010, Visual Studio 2008 or Visual Studio 2005 installed if you wish to debug RTX programs with the Visual Studio IDE. Note: To verify that your system is configured for RTX development in the Visual Studio environment, start Visual Studio and ensure that the RTX toolbar is displayed. 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 Manager. 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 clicking: 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 Existing Code To demonstrate using Visual Studio with RTX, you can start by building one of the sample programs. 2.1 Start a New Visual Studio Project Start Visual Studio by selecting it from the Start menu and then create a new project 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 determines 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 Project Add 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 either Win32.exe or RTX.rtss executable code. Set the Active solution configuration to one of the RTSS choices: RTSSDebug or RTSSRelease. 2.3 Build and Run the Program Select Build RtxSample1 or Rebuild RtxSample1 from the Build pull-down menu 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 in Windows Explorer. 3.0 Run Program from Visual Studio There are two ways in which an RTX.rtss executable program can be started from within Visual Studio: Use the Start Debugging button after setting solution configuration to RTSSDebug. Use the Debug pull-down menu to Start Without Debugging after setting up rtssrun command and arguments. 3.1 Use Visual Studio Start Debugging Button To set up a Visual Studio environment that will allow use of the Start Debugging button, follow the steps below. - 12 -
3.0 Run Program from Visual Studio Ensure that RTSSDebug is selected from the Solutions Configurations pull-down menu. Click the Start Debugging button, click Debug > Start Debugging or press F5. 3.2 Use the Debug Pull-Down Menu to Start Without Debugging To set up a Visual Studio environment that will allow use of the Debug pull-down menu, follow the steps below. From the Configurations drop-down menu, select RTSSRelease. - 13 -
From the Project menu, choose Properties to open the Property pages dialog box. After selecting Debugging from Configuration Properties, enter the full path name for the rtssrun.exe program and the path to your.rtss image and then click 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 Project Start Visual Studio by selecting it from the Start menu and then create a new project 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 determines 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 most cases, Multithreaded C Run-time support should also be included. Click Next to continue. - 20 -
4.0 Create a New Visual Studio Project Select Provide a program framework, select elements for a Periodic timer thread and then click Finish. 4.3 Modify the Program Open 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 the TimerHandler is called. 4.4 Build and Run an RTX Executable Set the Solution Configuration so that the program will be built as an RTSSRelease 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 or by typing into a command prompt: rtssrun RtxSample2-24 -
4.0 Create a New Visual Studio Project 4.5 Build and Run a Windows Executable The sample program can also be built as a Windows executable as described below. Set the Solution Configuration so that the program will be built as a Windows Debug executable. Select Build Solution from the Build pull-down menu. - 25 -
Run the resulting Windows executable program by double-clicking the file name in 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 rtss executable file, follow the steps listed below. Note: RTX does not register its lib and include directories with the system. If you will 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 environment. Open a Microsoft Visual Studio Tools command prompt from the Start menu by selecting: Start > Visual Studio > Visual Studio Tools > Visual Studio Command Prompt Note: If a Windows command prompt is used, you must first find and execute the file vcvars or vcvars32 from the installation directory for the version of Visual Studio 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 File Setting up the command prompt environment will ensure that the master make file C:\Program Files\IntervalZero\RTX\include\Rtx.mak will be found. The RTX master makefile is used by the sample program makefiles to produce 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 can specify Win32 executable (.exe) files in a makefile using rtx.mak because rtx.mak includes win32.mak. A Makefile Sample is available in the RTX Example Reference manual. 5.2 Makefile Variables The RTX master makefile uses the following variables: NODEBUG: Specifies that no debugging information is included in the executable image. RTSS_MTCRT: Links RTSS multi-threaded applications with the C run-time library. 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 command prompt window open to perform additional tasks described throughout this guide. 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 Program Create a working directory. This sample will use C:\Samples\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:\ProgramData\RTX\samples From the Visual Studio Command prompt window, change to your working directory 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 process (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 -subsystem: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 Process Execute 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 Process To 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 -