Release Note
MPI-RTX/RTSS Package

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:

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:

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.

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

Command Line Program Execution

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

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:

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:

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

Compiler Settings

Additional Include Directories:

Preprocessor Definitions

Runtime Library:

Linker Settings

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."