Welcome to the MPI-IntervalZero Real-Time Subsystem (RTSS) Support Library. The distribution was
built with Visual C++ 6.0 and tested using Visual C++ V6.0. The MPI library has been ported to support the
IntervalZero RTX/RTSS run-time environment version 6.5 with Windows XP only.
RTX/RTSS System Requirements
The MPI-RTSS release is built to operate on Windows XP.
Visual C++ DLLs
The MPI-RTSS is built using Microsoft Visual C++ V6.0. No Microsoft Visual C++ DLLs are included with this release. The following libraries are required in order to build the MPI-RTSS library:
The MPI-RTSS Support package, must be used with a compatible MPI Win32 release version. See MPI Version Numbering.
IntervalZero RTX/RTSS support has been tested on the 6.5 Release. This release assumes that RTX has already been installed. The following RTSS libraries and object files must be installed to build RTSS programs:
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 NuMega’s SoftICE debugger according to the set up instructions provided by IntervalZero.
Shared interrupts among ZMPs are supported with this release. However, it is required to verify the IRQs used by the ZMPs are not used by any other Windows 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 any other devices.
MPI RTX and Windows Applications
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\xmp\lib\WinRTSS and mei\xmp\app\WinRTSS. Key components of the distribution
- Release and debug versions of the MPI-RTSS DLL’s and the associated startup file mpiInit.exe.
The DLL’s are installed in mei\xmp\lib\WinRTSS in the subdirectories: Release, Debug, ReleaseStatic
and DebugStatic. The files mpiInit.exe & mpidll.rtss are installed in mei\xmp\bin\Win-RTSS.
- The project makefile for the MPI/XMP Sample applications for Microsoft Visual C++ V6.0. This
makefile, app.dsw, is installed into mei\xmp\app\WinRTSS.
- A valid installation of the appropriate version the MPI/XMP.
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.
Install the appropriate MPI and RTSS sofware releases.
- Install the MPI-WinNT (Windows 2000/XP) software
To install the MPI-WinNT software, insert the MDK CD-ROM or download the installation package from the FTP site. Contact Kollorgen Sales for login, filenames, and passwords. To start the set-up process, click on xx.xx.xx_WinNTSetup.exe. Follow the InstallShield instructions. The InstallShield will take care of installing the DLL and will also set the PATH environment variable to XMP\bin\WinNT for WinNT, XMP\bin\Win2000 for Win2000, and XMP\bin\WinXP for XP under the default installation directory.
- Install the MPI-RTSS software
To install the MPI-RTSS software, download the installation package from the FTP site. Contact Kollmorgen Sales for login, filenames, and passwords. To start the set-up process, click on xx.xx.xx_WinRTSSx.xSetup.exe. Follow the InstallShield instructions. The InstallShield will take care of installing the RTSS libraries, sample apps, and utilities. Be sure to install the MPI-RTSS into the same directory (default is C:\mei) that the MPI-WinNT was installed. Also, make sure to use the same version xx.xx.xx for the MPI-WinNT and MPI-RTSS installations.
To startup the RTSS environment and verify basic operation, follow the steps below:
- 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 XMP
Motion Controller should be listed under Motion Controller.
- Start up the MPI-RTSS DLL
Open the C:\mei\xmp\bin\winRTSS subdirectory and double-click on mpiInit.exe.
This will open the RTX/RTSS Console.
- You can also verify the mpiDLL.rtss is running via the RTX SDK->RTX Tools->RTSS Task Manager.
- From Microsoft Developer Studio, select Open Workspace and browse to C:\mei\xmp\app\WinRTSS
In the Files of type field, select Workspace file (*.dsw), then select app.dsw.
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
- In Microsoft Visual C++, set the current configuration to coffee and build it.
- To execute the program coffee, use the rtssrun utility to launch the task from the command prompt. 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 mei\xmp\app\WinRTSS\coffee\Release
- Type: C:\mei\xmp\app\WinRTSS\coffee\Release> rtssrun coffee.rtss
- coffee.rtss can also be executed from Explorer by navigating to the directory
C:\mei\xmp\app\WinRTSS\coffee\Release 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 C++.
The above procedure is based upon a standard installation of RTX into C:\MEI. If it was installed elsewhere,
make the appropriate changes in the Project settings.
General Change History
There are two component parts to the MPI-RTSS: a Windows Application and an RTSS DLL. All RTSS
applications, which access the RTSS DLL, must be executed after the DLL is already running. The RTSS
DLL must be invoked with the Windows Application mpiInit.exe.
The RTSS DLL assumes a single version of the library is executing at any given time. The RTSS DLL subsumes
system resources from the driver and all MPI interrupts are processed by the RTSS subsystem.
RTSS and standard Windows processes should NOT be executed at the same time,
although some processes are permissible. Procedures that generate interrupts from
the XMP can cause unpredictable system behavior and should not be attempted.
MPI Static Library
A MPI Static library was added in version 20000913 to the WinRTSS release. The utility mpiInit.exe
should be used with the -static command-line option to avoid from loading the WinRTSS support DLL into
memory. The new static library is located at (C:\MEI)\XMP\lib\WinRTSS\debugStatic\mpStatic.lib.
RTX Interrupt Priority
Version 20000802 added the ability to set the RTX interrupt priority for the XMP interrupt vector. The RTX
shared memory data structure passes the priority to platform.c from mpiInit.c. The priority is a commandline
option of xmp\bin\winrtss\mpiInit.exe. The new 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).
The MPI-RTSS DLL provides an interface to the XMP 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/XMP 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,
mpiDLL.rtss, builds two configurations:
- Debug – multi-threaded
- Release – multi-threaded
mpiDLL.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/XMP library functions. It may be called from any .rtss program which links with its library,
mpiDll.lib. Note: for any .rtss program to access RTSS-DLL functions, mpiDLL.rtss must be running.
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 mpiDLL.rtss under RTSS
- Providing initialization information
- Informing the device driver that it is going into a standby state
- Automatically setting RTX interrupt priority for the XMP 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 XMP controller, since these interrupts are now being intercepted
by the RTSS.
Running XMP support utilities under RTX
The Windows driver is still available to communicate with the XMP or operate in a non-invasive mode while
RTSS processes are executing, in certain LIMITED cases (MPI/XMP support utilities), noted below:
- reset program
- flash program
- VM3 program
- Motion Console
- Motion Scope
this makes MPI/XMP support utilities available (such as reset, flash and vm3).
The interface to mpiInit.exe is as follows:
For the example above, the appropriate directories and paths must be provided.
There are two versions of mpiInit.exe – debug and release. There is no explicit tie between the debug
and release versions of mpiInit and the debug and release versions of mpiDll.rtss, and hence either version
of mpiInit can invoke any version of mpiDll.rtss.
MPI/XMP Sample Applications
This release installs .dsw files for building the sample applications under Microsoft Visual C++ V6.0.
The .dsw files provide an interface to build from the command line using nmake –f file.dsw where file is
the name of the makefile for the specific application.
The following applications have been tested to properly execute under the RTSS environment:
The funciton meiPlatformKey() normally waits for any key on the user’s keyboard to be pressed. However,
in RTSS, meiPlatformKey() can be executed in one of two modes: MPIWaitFOREVER and MPIWaitPOLL.
The semantics have been modifed so that meiPlatformKey(MPIWaitFOREVER) returns after 10 seconds
and meiPlatformKey(MPIWaitPOLL) returns after it has been called 10 times.
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 0x20000 (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 (0x20000 bytes) 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
RTSS Resets the Machine
If an MPI application, running under Windows generates any interrupts, running mpiInit.exe will lock-up
and reboot the host computer. This can be avoided by rebooting the host machine before running mpi-
Init.exe after any Windows mpi Applications have been run. Motion Console and Motion Scope will not
effect the execution of mpiInit.exe.
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.
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."