.

Release Note
MPI-RTX/RTSS Package

 
Current Version
RTX/RTSS Version
8.1
MPI Version

RTX/RTSS System Requirements

Operating Systems
The MPI-RTSS release is built to operate on Windows XP.

Visual C++ DLLs
The MPI-RTSS is built using Microsoft Studio 2005. No Microsoft Visual C++ DLLs are included with this release. The following libraries are required in order to build the MPI-RTSS library:

MPI/XMP Library
The MPI-RTSS Support package, must be used with a compatible MPI Win32 release version. See MPI Version Numbering.

RTX/RTSS DLLs
IntervalZero RTX/RTSS support has been tested on the 8.1 Release. This release assumes that RTX has already been installed. The following RTSS libraries and object files must be installed to build RTSS programs:

 
  • rtapi_rtss.lib
  • rtx_rtss.lib
  • w32_dll.lib
  • startCRT.obj

Debugging
There are both Debug and Release versions of the MPI-RTSS libraries. MPI-RTSS test applications can be debugged using either the Microsoft’s WinDbg.exe or Visual Studio 2005 according to the set up instructions provided by IntervalZero.

 

WARNING!
Shared interrupts among ZMPs are supported with this release. However, IRQs used by ZMP controllers must NOT be shared with any other device.

Use the Device Manager (found in Control Panel -> System -> Hardware -> Device Manager) to view the resources by type. Check to make sure that the Motion Controller does not share interrupts with other devices.

MPI RTX and Windows Applications

WARNING!
Do NOT run MPI Windows applications and MPI RTX applications simultaneously. The MPI library and the RTX library are two independent libraries. Interrupt handling, controller reset, semaphore protection, and controller read/write access is NOT supported across the RTX and Windows platforms simultaneously. If you run MPI Windows and RTX applications simultaneously, unstable and unpredictable behavior may result!

Installing the Distribution on the Host System

The MPI-RTSS installation consists of an InstallShield base distribution. All files are installed into the new subdirectories: mei\mdk\xx.xx.xx\WinRTSS and mei\mdk\xx.xx.xx\MPI\Lib\WinRTSS. Key components of the distribution are:

 
  • Release and debug versions of the MPI-RTSS DLL’s and the associated startup file mpiInit.exe. The DLL’s are installed in the Lib subdirectories: Release, Debug, ReleaseStatic and DebugStatic. The files mpiInit.exe & mpivc80.rtss are installed in mei\mdk\xx.xx.xx\WinRTSS.

  • The MDK project solution file mdk.sln for Microsoft Studio 2005 is installed in ...mei\xmp\app\WinRTSS.

Installation Procedure

WARNING!
If you are upgrading from a previous MPI software release, you will need to remove or archive all previous releases. This will prevent any conflicts between old and new files. To remove the previous MPI software release, select Start -> Control Panel -> Add/Remove Programs. Select the MPI Development Toolkit entry and click on the Add/Remove button. NOTE: The MPI software release can also be removed by running the MPI InstallShield and choosing the remove option.

Installation Steps

Install the appropriate MPI-Win32 and MPI-WinRTSS software packages.

 
  1. Install the MPI-Win32 (Windows XP) software
    To install the MPI-Win32 software, download the installation package from the supplied website link. Contact Kollmorgen Sales to purchase software. To start the set-up process, click on MPI_xx.xx.xx_Win32_Setup.exe. Follow the InstallShield instructions. The InstallShield installs the DLL and also sets the PATH environment variables.

  2. Install the MPI-RTSS software
    To install the MPI-RTSS software, download the installation package from the supplied website link. Contact Kollmorgen Sales to purchase software. To start the set-up process, click on MPI_xx.xx.xx_WinRTSS_Setup.exe. Follow the InstallShield instructions. The InstallShield installs the RTSS libraries, sample apps, and utilities. Be sure to install the MPI-RTSS into the same directory that the MPI-Win32 was installed. Also, make sure to use the same version xx.xx.xx for the MPI-Win32 and MPI-RTSS installations.

To startup the RTSS environment and verify basic operation, follow the steps below:

 
  1. After installing RTSS (using the InstallShield), verify that the device driver is running.
    Go to the Start->Settings->Control Panel window, click on System->Hardware tab->Device Manager. To verify that the driver is running, click on the Motion Controller icon. An ZMP Motion Controller should be listed under Motion Controller.
  2. Start up the MPI-RTSS DLL
    Open the C:\Program Files\MEI\MDK\xx.xx.xx\WinRTSS subdirectory and double-click on mpiInit.exe.
    This will open the RTX/RTSS Console.




  1. You can also verify the mpiVC80.rtss is running via the RTX SDK->RTX Tools->RTSS Task Manager.



  2. From Microsoft Visual Studio, select Open Project/Solution and browse to C:\Program Files\MEI\MDK\xx.xx.xx\MPI\build\WinRTSS\V2005
    In the Files of type field, select Workspace file (*.sln), then select mdk.sln.
    Verify that the directories have been set up to build with the IntervalZero library and include files, by selecting Tools->Options->Directories and adding:
           Include Files – C:\Program Files\IntervalZero\RTX SDK\Include
           Lib Files – C:\Program Files\IntervalZero\RRX SDK\Lib
  3. In Microsoft Visual Studio, set the current configuration to coffee and build it.
  4. To execute the program coffee, use the rtssrun utility to launch the task from the command prompt or double-click the coffee.rtss file. Please see the following section.

Command Line Program Execution

To execute the program coffee from the command line, after Step 6:

 
  • Open an MS-DOS command window.
  • Type: C:\> cd Program Files\MEI\MDK\xx.xx.xx\MPI\examples\WinRTSS\VS2005\coffee\release
  • Type: rtssrun coffee.rtss


  • coffee.rtss can also be executed from Explorer by navigating to the directory and double-clicking on coffee.rtss.

If there are any problems with building or execution of the sample applications, verify that the RTX/RTSS libraries are properly installed in the locations being used by Microsoft Visual Studio.

The above procedure is based upon a standard installation of RTX into C:\Program Files\MEI. If it was installed elsewhere, make the appropriate changes in the Project settings.

MPI Static Library

A MPI Static library is available. The utility mpiInit.exe should be used with the -static command-line option to avoid from loading the WinRTSS support DLL into memory. The static library is located at ...\lib\WinRTSS\VS 2005\Debug Static and \Release Static.

RTX Interrupt Priority

The RTX interrupt priority for the controller interrupt vector can be configured. The RTX shared memory data structure passes the priority to platform.c from mpiInit.c. The priority is a commandline option of mpiInit.exe. The syntax is:
      mpiInit (-priority #)
where # is any number from 0 - 127. By default the priority level is set to the highest priority level possible in RTX, which is RT_PRIORITY_MAX (127).

MPI-RTSS DLL

The MPI-RTSS DLL provides an interface to the controller under RTSS. It executes from within the RTSS process environment and provides a real-time environment under Windows.

The MPI-RTSS interface to the MPI DLL is similar to the standard Windows version, but certain functionality is not supported under IntervalZero. This includes:
       - Keyboard input
       - Interfacing to device drivers directly (devIoControl())
       - Various C-library and Win32 API functions.
Please refer to the IntervalZero documentation for a complete list of supported functionality.

IntervalZero Modifications to Windows HAL (Hardware Abstraction Layer)
IntervalZero has modified the Windows HAL (Hardware Abstraction Layer) which provides the main interface between the hardware and Windows. The RTSS intercepts all interrupts from the hardware prior to passing them onto the Windows kernel.

RTX Starvation Timeout
The RTSS environment provides its own scheduler which schedules RTSS applications before Windows processes get scheduled – hence the opportunity to starve Windows processes. It is important to configure the RTSS with an appropriate starvation timeout value so that RTSS processes behave accordingly.

If the execution of a RTSS process exceeds the starvation timeout limit, assuming one is provided (it can be disabled), the RTSS process will be terminated by RTSS. Hence, not exceeding this timeout limit (or disabling it) is very important when performing system intensive real-time processing.

To adjust the RTX Starvation Timeout:

 
  • Go to Settings->Control Panel from the Start Menu in Windows. Open the Control Panel window.
  • Double-click on RTX Settings. A dialog box will display the RTX Dialog box.
  • Either click the Disable check-box, or enter the appropriate value into the Starvation Timeout entry box.

Communication between Win32 and RTSS Applications
RTX (Real-Time Extensions) supports communication between Win32 and RTSS applications.

This allows for the MPI-RTSS DLL to interface with a Win32 application, mpiInit.exe, responsible for communicating with the meixmp device driver and providing base initialization parameters. The program mpiInit.exe must be used to correctly invoke the MPI-DLL. The MPI-RTSS DLL builds two configurations:
      - Debug – multi-threaded
      - Release – multi-threaded

mpiVC80.rtss is not a Windows DLL, but an RTSS application with external entry points. The IntervalZero model provides for this type of RTSS application. The MPI-RTSS DLL has external entry points for all of the current MPI library functions. It may be called from any .rtss program which links with its library. Note: for any .rtss program to access RTSS-DLL functions, the MPI library must be running.

MPIInit (mpiinit.exe)

Since RTX does not provide direct access to Windows device drivers, the mpiInit.exe program has been developed to interface with the meixmp device driver when starting up the MPI-RTSS DLL.

The mpiInit.exe utility provides various functions:

 
  • Invoking MPI library under RTSS
  • Providing initialization information
  • Informing the device driver that it is going into a standby state
  • Automatically setting RTX interrupt priority for the controller interrupt vector

The mpiInit.exe utility should be used with the -static command-line option to avoid from loading the Win- RTSS support DLL into memory. The new static library is located at (C:\MEI)\XMP\lib\WinRTSS\debug-Static\mpiStatic.lib.

The mpiDLL.rtss communicates with the meixmp Windows device driver. The
Windows device driver is still active while the MPI-RTSS DLL is executing, but the Windows driver no longer receives interrupts from the controller, since these interrupts are now being intercepted by the RTSS.

RTSS Project Properties

The follwing VS2005 project settings are required to build MPI-RTSS applications.

User Macros

 
  • MpiLibraryName: mpivc80, mpivc80d, mpivc80Static, or mpivc80dStatic
  • ConfigurationDir: Debug, Release, DebugStatic, or ReleaseStatic
  • MdkRootDir: base directory for MDK

Compiler Settings

Additional Include Directories:

 
  • $(MdkRootDir)\MPI\include
  • $(MdkRootDir)\MPI\apputil
  • $(RtxSdkDir)\include

Preprocessor Definitions

 
  • Debug and Release: MPI_DECL1=__declspec(dllimport);MPI_DECL2=__stdcall;
  • Static: MPI_DECL1=;MPI_DECL2=__stdcall

        WIN32;UNDER_RTSS;VISUALSTUDIO=8;_RTSSs_;MPI_PLATFORM_WINRTSS;    MPI_NO_DEPRECATIONS;_CRT_SECURE_NO_DEPRECATE;MPI_ASSERT

  • Debug: _DEBUG
  • Release: NDEBUG
  • Static lib: MPI_RTSS_STATIC
  • Struct Member Alignment: 8 Bytes (/Zp8

Runtime Library:

 
  • Debug: Multi-threaded Debug (/MTd)
  • Release: Multi-threaded (/MT)

Linker Settings

 
  • Output File: Change extension to .rtss
  • Additional Dependencies: startupCrt.obj rtxlibcmt.lib oldnames.lib rtapi_rtss.lib rtx_rtss.lib apputil.lib $(MpiLibraryName).lib
  • Ignore All Default Libraries: Yes (/NODEFAULTLIB)
  • Ignore Specific Library: libc;;libcmt;libcmtd
  • Additional Library Directories:
    - $(RtxSdkDir)\lib
    - $(RtxSdkDir)\lib\VisualStudio8
  • System: Driver (/DRIVER
  • Entry Point: _RtapiProcessEntryCRT@8 Stack Reserve Size: 100000 (or larger)
  • Stack Commit Size: 100000 (or larger)

    $(MdkRootDir)\MPI\lib\WinRTSS\VS2005\$(ConfigurationDir)

Application Thread Stack Size

MS Visual Studio projects for RTX have 8192 bytes allocate for the default stack size. Applications that make calls to the MPI should configure the stack allocation Reserve and Commit to 100000 (128 kByte) in the Project Settings:

Create Thread Stack Size

If you are using CreateThread(...) to launch a thread that will make calls to the MPI library, be sure to specify an appropriate stack size. We recommend configuring the stack size to 128 kBytes for the MPI library. If you do not allocate enough stack space, RTX may fail with stack overflow errors or Green Screen (GSOD) non-recoverable exception errors.

Please consult the RTX documentation for details about CreateThread(...) and stack size configuration.

Known Bugs and Issues

Support of File and Device I/O
RTX allows two options for file input and output (I/O). You can write to the supported file I/O functions in the Win32 API or to the supported file I/O functions in the C run-time library. The API delivers low-overhead, fast access to Windows file I/O capabilities using standard APIs. A subset of CreateFile flags are supported with file I/O. Please refer to the Reference Guide for more details. File I/O does not include support for asynchronous file operations.

Because RTSS applications have no current-directory notion, RTSS file I/O requests must use fully qualified path names, such as:

      c:\temp\MyFile.txt (for a file system object)

      \\.\MyDevice0 (for a device object)

RTSS file I/O calls are made from the Windows kernel environment: RTX actually translates Win32 names such as c:\MyFile.txt and \\.\MyDevice0 to Windows internal names \??\c:\MyFile.txt and \Device\MyDevice0, respectively. Therefore, you can use Windows internal names from your RTSS applications, although such calls fail in Win32. Using an internal Windows name lets you access a device object for which Win32 has no symbolic link, such as \Device\beep or \Device\Harddisk0\Partition1\testfile.txt.

With boot-time file I/O, you may only use paths such as \\Device\\Harddisk0\\Partition1\foo.txt because paths such as \\??\\C:\\foo.txt and C:\\foo.txt are not supported.

WARNING!
The RTSS API cannot be used to create or open files over a network. The path should be set to a file location on the local hard drive or other local device. If you try to access files over a network from RTX, the MPI will return a "File Open Error."


       Legal Notice  |  Tech Email  |  Feedback
      
Copyright ©
2001-2010 Motion Engineering